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PREFACE 



This book describes all IBM data management except for VSAM (virtual storage access 
method) and specialized applications such as the time sharing option (TSO), graphics, 
teleprocessing, optical character readers, optical reader-sorters, and magnetic character 
readers. These specialized applications are described in separate publications that are 
listed in IBM System/ 3 70 Bibliography .GC20-0001. To learn about VSAM or to write 
programs that create and process VSAM data sets, refer to: 

• Planning for Enhanced VSAM Under OS/VS, GC26-3842, which introduces 
VSAM and describes its concepts and functions. 

• OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide, GC26-3838, 
which describes how to create VSAM data sets and code the macro instructions 
required to process them. 

• OS/VS2 Access Method Services, GC26-3841, describes the service program 
commands used to manipulate VSAM data sets. 

• OS/VS Virtual Storage Access Method (VSAM) Options for Advanced Applications, 
GC26-3819, which describes applications not required in the normal use of VSAM. 

If you know how to write assembler-language programs and use job control statements, 
you can use this book and OS/VS 2 MVS Data Management Macro Instructions, 
GC26-3873, to write programs that create and process data sets. To use this book you 
must have basic knowledge of the operating system as contained in OS/VS 2 Release 3 
Guide, GC28-0770; of assembler language as described in OS/VS-DOS/VS-VM/370 
Assembler Language, GC33-4010; and of job control language (JCL) as explained in 
OS/VS2 JCL, GC28-0692. 

This book has three parts: 

"Part 1: Introduction to Data Management" introduces you to the characteristics of data 
sets, how you name them, how the system catalogs them, and how you format the 
records in them. The format of tracks on a direct-access storage device is explained 
briefly. 

Part 1 also describes the data control block (DCB) and the information it supplies to the 
operating system. Special processing routines that you specify in the DCB macro 
instruction are also explained in this section. 

In "Part 2: Data Management Processing Procedures" there is an explanation of 
data-processing techniques that includes the macro instructions for the queued access 
technique and the basic access technique and the macro instructions for analyzing input 
and output errors. The section on data-processing techniques also tells how to select an 
access method and how to begin and end processing of a data set. 

The section "Buffer Acquisition and Control" in Part 2 explains three different methods 
you can use to obtain buffers and the macro instructions you use with each method. This 
section also describes ways to control buffers: simple buffering for the queued access 
technique, direct buffering and dynamic buffering for the basic access technique. In 
addition, for the queued access technique, there is an explanation of the four modes of 
moving the records in virtual storage: move mode, data mode, locate mode, and 
substitute mode. Macro instructions for controlling buffers are described here, too. 

The next four sections of Part 2 concern processing data sets of four different types: a 
sequential data set, a partitioned data set, an indexed sequential data set, and a direct 
data set. They explain the organization of the data sets and the macro instructions used 
to process them. In the examples the macro instructions are coded in just enough detail 
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to make the examples clear. For a complete description of the operands and options 
available, see OS/VS2 MVS Data Management Macro Instructions, GC26-3873. 

"Part 3: Data Set Disposition and Space Allocation" tells you how to figure the amount 
of space you need for a data set on a direct-access storage device and how to request that 
space in your JCL DD statement. You are given special directions for allocating space 
for a partitioned data set and an indexed sequential data set. Part 3 also tells how to 
indicate in the JCL DD statement the status of the data set at the beginning of and 
during processing and how to indicate what you want the system to do with the data set 
when processing has terminated. You also are told how to use the DD statement to route 
the data set to a system output writer, to concatenate data sets, to catalog data sets, and 
to protect confidential data sets. 

Appendix A describes data set labeling. Appendix B explains control characters you can 
use to control card punches and printers. A glossary of acronyms and abbreviations used 
in this book and the index follow Appendix B. 

The following manuals are referred to in the text. 

OS/VS Message Library: VS2 System Codes, GC38-1008 

OS/VS Message Library: VS2 System Messages, GC38-1002 

OS/VS2 JCL, GC28-0692 

OS/VS2 MVS CVOL Processor, GC26-3864 

OS/VS2 MVS Resource Access Control Facility (RACF): General Information 
Manual, GC28-0722 

OS/VS2 Supervisor Services and Macro Instructions, GC28-0683 

OS/VS2 System Programming Library: Data Management, GC26-3830 

OS/VS2 System Programming Library: Debugging Handbook, Volume I, 
GC28-0708 

OS/VS2 System Programming Library: Debugging Handbook,Volume 2, 
GC28-0709 

OS/VS2 System Programming Library: Debugging Handbook, Volume 3, 
GC28-0710 

OS/VS2 System Programming Library: Initialization and Tuning Guide, 
GC28-0681 

OS/VS2 System Programming Library: Service Aids, GC28-0633 

OS/VS 2 System Programming Library: Supervisor, GC28-0628 

OS/VS2 System Programming Library: System Generation Reference, GC26-3792 

IBM 3800 Printing Subsystem Programmer's Guide, GC26-3846 

IBM 3890 Document Processor Machine and Programming Description, GA24-3612 

OS Data Management Services and Macro Instructions for IBM 1419/1275, 
GC21-5006 

OS and OS/VS Programming Support for the IBM 3505 Card Reader and IBM 
3525 Card Punch, GC21-5097 

OS/VS IBM 3886 Optical Character Reader Model 1 Reference, GC24-5101 

OS/VS Mass Storage System (MSS) Planning Guide, GC35-0011 

OS/VS Mass Storage System (MSS) Services: General Information, GC35-0016 
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. OS/VS Tape Labels, GC26-3795 

. OS/VS Utilities, GC35-0005 

In this manual, any references made to an IBM program product are not intended to 
state or imply that only IBM's program product may be used; any functionally equivalent 
program may be used instead. This manual has references to the following IBM program 
products: 

• RACF-Resource Access Control Facility Program Number, 5740-XXH 
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SUMMARY OF AMENDMENTS 



New Programming Support 

The information to support the IBM 3203 model 5 printer has been included. For 
additional information about the IBM 3203 Printer, see IBM 3203 Printer Component 
Description and Operator's Guide, GA33-1515. 

Service Changes 

"Data Set Identification" has been updated concerning the cataloging of data set names. 

"Basic Access Techniques" has been updated concerning the overlapping of I/O 
requests with BDAM. 

A clarification has been added to "Chained Scheduling for I/O Operations." 

Another restriction when search direct cannot be used has been added to the section 
"Search Direct for Input Operations (Except 5740-AM3)." 

The section "Search Direct for Input Operations (5740-AM3)" has been updated. 

The restriction for chained scheduling has been updated under "Determining the Length 
of a Record when using the BSAM READ macro." 

The section "FIND-Position to a Member" has been updated concerning the requirement 
to close and reopen a data set. 

A new section "Processing a Partitioned Data Set Residing on MSS" has been added to 
"Processing a Partitioned Data Set." 

The section "Indexed Sequential Buffer and Work Area Requirements" has been 
updated concerning a high level index greater than 65,535 bytes. 

The section "Specifying Space Requirements" has been updated concerning cylinder 
allocation. 

The section "Absolute Generation and Version Numbers" has been updated. 

The section "Relative Generation Numbers" has been updated and the section 
"Programming Considerations for Multiple Step Jobs" has been added. 



August, 1978 



The information contained in the System Library Supplement GC26-3892, OS/VS2 
MVS System Security Support Selectable Unit: Data Management Services-SU32 
(5752-832) has been incorporated into this publication by this Technical Newsletter. 

A note has been added to the description of the DSORG operand concerning the 
creation of a direct data set. This is in "Data Set Organization (DSORG)." 

Under "Synchronous Error Routine Exit (SYNAD)," a note has been added concerning 
EROPT and a physical block of data. 

Under "Standard User Label Exit," the specification of labels by use of the LABEL= 
parameter in a DD statement has been updated and the defer input trailer label exit 0C 
has been qualified. 

Under "User Totaling" (BSAM and QSAM only)," a note has been added regarding the 
user totaling facility. 
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Under "End of Volume Exit," a note has been added concerning concatenated data sets 
with unlike attributes. 

Under "Opening and Closing a Data Set," the description of an indeterminate error has 
been updated. 

The description of RLSE under "CLOSE-Terminate Processing of a Data Set" has been 
updated. 

The default value for BUFNO when using QSAM has been updated. 

A note has been added regarding the 4-byte buffer chain pointer under 
"FREEPOOL-Free a Buffer Pool." 

In the section "Chained Scheduling for I/O Operations," a new item has been added to 
the chained scheduling restrictions. A restriction for chained scheduling with printer 
channel control tapes has also been added. 

Under "Updating a Sequential Data Set," a new rule has been added for Locate mode. 

Under "Find-Position to a Member," a note has been added regarding the search of a 
concatenated series of directories. 

In the section "Creating an Indexed Sequential Data Set," the paragraph concerning 
blocked records has been updated. 

A paragraph has been added about subtasking under the heading "Sharing a BISAM 
DCB between Related Tasks." 

The figure, "Directly Updating an Indexed Sequential Data Set" has been updated. 

In the section "Processing a Direct Data Set," a paragraph has been added concerning 
the DSORG parameter. 

Under "Adding or Updating Records on a Direct Data Set," a note has been added 
regarding extended search. 

Under "Concatenating Sequential and Partitioned Data Sets," a note has been added 
about spool data sets, and about data sets with unlike attributes. 

Under "Relative Generation Number," the description of skipping absolute generation 
numbers has been expanded. Also the paragraph concerning cataloging via JCL has been 
updated. The paragraph concerning cataloging of new generation data groups has been 
updated also. 

Sequential Access Method-Extended (SAM-E) Release 1 
(5740-AM3) 

BPAM, BSAM, and QSAM support of direct-access storage devices (except BSAM 
MACRF=WL, create BDAM data set) has been modified to internally use the 
EXCPVR interface to IOS. This modification includes the functions of the chained 
scheduling option (OPTCD=C) and the search-direct option OPTCD=Z). These 
options, therefore, need not be requested and are ignored if requested. 

OS/VS2 MVS System Security Support (5752-832) 

Documentation to support tape volumes has been added to the section "RACF 
Protection for NonVS AM Data Sets." 



14 OS/VS2 MVS Data Management Services Guide 



Page of GC26-3875-0 
Added June 29, 1979 
By TNL GN26-0944 



OS/VS2 MVS IBM 3800 Printing Subsystem (VS2.03.810) 



To use the SETPRT macro to support the IBM 3800 Printing Subsystem requires 
OS/VS2 MVS IBM 3800 Printing Subsystem Selectable Unit (VS2.03.810) 



OS/VS2 MVS Data Management (VS2.03.808) 
Open Extend Support 



RACF Support 



The EXTEND and OUTINX options will be supported for the OPEN macro. These 
options allow the user to change the disposition of a data set to MOD. In all other ways 
EXTEND and OUTINX are equivalent to the OUTPUT and OUTIN options, 
respectively. 

These new options will allow users of SAM and ISAM to add records to the end of an 
existing data set even though DISP=OLD/NEW/MOD/SHR was specified. In the past, 
the only way to add records to the end of the data set was to specify DISP=MOD on the 
DD statement and OUTPUT on the OPEN macro or to specify INOUT on the OPEN 
macro and read to end-of-file or use the OPEN TYPE=J macro. 



A section titled, "RACF Protection for NonVSAM Data Sets (VS2.03.808 only)" has 
been added to describe the five levels of access authority which a user may have to a 
RACF-defined data set. 
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The IBM 3350 Direct Access Storage and IBM 3344 Direct Access Storage 
Device are now supported under VS2. This information is provided for 
planning purposes only until the products become available. 



Release 3 

New Programming Support 



Editorial Changes 



The IBM 3850 Mass Storage System (MSS) is supported with this release. 
The MSS virutal volumes are functionally equivalent to the 3330/3333 Disk 
Storage, Model 1. For information on MSS, see OS/VS Mass Storage System 
(MSS) Planning Guide, GC35-0011. MSS information is provided for 
planning purposes only until the system is available. 

Exchange buffering support was removed for VS2 because it can badly affect 
performance in a virtual system. If exchange buffering is specified, it will be 
ignored by the system. If exchange buffering is denied by the system for any 
reason, move mode will be used instead. Move mode is compatible with 
exchange buffering. 

Chained scheduling will now be supported by VS2 whether it is requested or 
not (except for printers and format-U input records). This support was 
changed to improve performance in a virtual system. Chained scheduling will 
not be used where it previously was not allowed. 

For QSAM, BUFNO will now default to 5 buffers instead of 2. 



• The explanation of the EODAD routine has been expanded. 

• An explanation of how the SYNAD routine functions with QISAM load 
mode has been added. 

• A list of restrictions when sharing a direct data set in multitasking mode 
has been added. 

• The section titled "Updating a Sequential Data Set" has been expanded. 

• A section titled "Writing a Short Block When Using the BSAM WRITE 
Macro" has been added. 

• An explanation of the capacity record (R0) has been added to the section 
titled "Creating a Direct Data Set." 



Summary of Amendments 15 



PART 1: INTRODUCTION TO DATA 

MANAGEMENT 

Data Set Characteristics 



The data management programs of the operating system help you achieve maximum 
efficiency in managing the mass of data associated with the many programs that are 
processed at your installation by providing systematic and effective means of organizing, 
identifying, storing, cataloging, and retrieving all data, including programs, processed by 
the operating system. 

Data set storage control, along with an extensive catalog system, makes it possible for 
you to retrieve data by symbolic name alone, without specifying device types and volume 
serial numbers. In freeing computer personnel from maintaining involved volume serial 
number inventory lists of stored data and programs, the catalog reduces manual 
intervention and the likelihood of human error. 

Data sets stored within the cataloging system can be classified according to installation 
needs. For example, a sales department could classify the data it uses by geographic area, 
by individual salesman, or by any other logical plan. 

The cataloging system also makes it possible for you to classify successive generations or 
updates of related data. These generations can be given an identical name and 
subsequently be referred to relative to the current generation. The system automatically 
maintains a list of the most recent generations. 

You can request data from a direct-access volume, a remote terminal, or a tape volume, 
and data organized sequentially or directly, in essentially the same way. In addition, data 
management provides: 

• Allocation of space on direct-access volumes. Flexibility and efficiency of 
direct-access devices are improved through greater use of available space. 

• Automatic retrieval of data sets by name alone. 

• Freedom to defer specifications such as buffer length, block size, and device type until 
a job is submitted for processing. This permits the creation of programs that are in 
many ways independent of their operating environment. 

Control of confidential data is provided by the data set security part of the operating 
system. You can prevent unauthorized access to payroll data, sales forecast data, and all 
other data sets that require special security attention. An individual can use a 
security-protected data set only after furnishing a predefined password. 

Input/output routines are provided to efficiently schedule and control the transfer of 
data between storage and input/output devices. Routines are available to: 

• Read data 

• Write data 

• Translate data from ASCII (American National Standard Code for Information 
Interchange) to EBCDIC (Extended Binary Coded Decimal Interchange Code) and 
back 

• Block and deblock records 

• Overlap reading, writing, and processing operations 

• Read and verify volume and data set labels 

• Write data set labels 
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• Automatically position and reposition volumes 

• Detect error conditions and correct them when possible 

• Provide exits to user-written error and label routines 

OS/VS data management programs also provide for a variety of methods for gaining 
access to a data set. The methods are based on data set organization and data access 
technique. 

OS/VS data sets can be organized in four ways: 

• Sequential: Records are placed in physical rather than logical sequence. Given one 
record, the location of the next record is determined by its physical position in the 
data set. Sequential organization is used for all magnetic-tape devices, and may be 
selected for direct-access devices. Punched tape, punched cards, and printed output 
are sequentially organized. 

• Indexed Sequential: Records are arranged in sequence, according to a key that is a 
part of every record, on the tracks of a direct-access volume. An index or set of 
indexes maintained by the system gives the location of certain principal records. This 
permits direct as well as sequential access to any record. 

• Direct: The records within the data set, which must be on a direct-access volume, may 
be organized in any manner you choose. All space allocated to the data set is available 
for data records. No space is required for indexes. You specify addresses by which 
records are stored and retrieved directly. 

• Partitioned: Independent groups of sequentially organized records, called members, 
are in direct-access storage. Each member has a simple name stored in a directory that 
is part of the data set and contains the location of the member's starting point. 
Partitioned data sets are generally used to store programs. As a result, they are often 
referred to as libraries. 

Requests for input/output operations on data sets through macro instructions employ 
two techniques: the technique for queued access and the technique for basic access. 
Each technique is identified according to its treatment of buffering and synchronization 
of input and output with processing. The combination of an access technique and a given 
data set organization is called an access method. In choosing an access method for a data 
set, therefore, you must consider not only its organization, but also what you need to 
specify through macro instructions. Also, you may choose a data organization according 
to the access techniques and processing capabilities available. 

The code generated by the macro instructions for both techniques is optionally 
reenterable depending on the form in which parameters are expressed. 

In addition to the access methods provided by the operating system, an elementary 
access technique called execute channel program (EXCP) is also provided. To use this 
technique, you must establish your own system for organizing, storing, and retrieving 
data. Its primary advantage is the complete flexibility it allows you in using the computer 
directly. 

An important feature of data management is that much of the detailed information 
needed to store and retrieve data, such as device type, buffer processing technique, and 
format of output records need not be supplied until the job is ready to be executed. This 
device independence permits changes to those specifications to be made without changes 
in the program. Therefore, you may design and test a program without knowing the exact 
input/output devices that will be used when it is executed. 

Device independence is a feature of both access techniques for processing a sequential 
data set. To some extent, you determine the degree of device independence achieved. 



18 OS/VS2 MVS Data Management Services Guide 



Page of GC26-3875-0 
Revised June 29, 1979 
By TNL GN26-0944 

Many useful device-dependent features are available as part of certain macro 
instructions, and achieving device independence requires some selectivity in their use. 



Data Set Identification 



Data Set Storage 



Any information that is a named, organized collection of logically related records can be 
classified as a data set. The information is not restricted to a specific type, purpose, or 
storage medium. A data set may be, for example, a source program, a library of macro 
instructions, or a file of data records used by a processing program. 

Whenever you indicate that a new data set is to be created and placed on auxiliary 
storage, you (or the operating system) must give the data set a name. The data set name 
identifies a group of records as a data set. All data sets recognized by name (referred to 
without volume identification) and all data sets residing on a given volume must be 
distinguished from one another by unique names. To assist in this, the system provides a 
means of qualifying data set names. 

A data set name is one simple name or a series of simple names joined together so that 
each represents a level of qualification. For example, the data set name 
DEPT58.SMITH.DAT A3 is composed of three simple names. Proceeding from the left, 
each simple name is a category within which the next simple name is a subcategory. The 
first name is referred to as the high level index, the last as the low level index. 

Each simple name consists of from 1 to 8 alphameric characters, the first of which must 
be alphabetic. The special character period (.) separates simple names from each other. 
Including all simple names and periods, the length of the data set name must not exceed 
44 characters. Thus, a maximum of 22 simple names can make up a data set name. 

Data set names cannot be cataloged in a CVOL if a name is already cataloged whose 
levels match the highest or higher levels of the specified name. For example, the qualified 
name A.B.C.D cannot be cataloged if the name A.B. or A.B.C. is already cataloged, but 
the name A.B.C.D can be cataloged if AB.C or A.B.C.E is cataloged. 

To permit different executions of a program to process different data sets without 
program reassembly, the data set is not referred to by name in the processing program. 
When the program is executed, the data set name and other pertinent information (such 
as unit type and volume serial number) are specified in a job control statement called the 
data definition (DD) statement. To gain access to the data set during processing, 
reference is made to a data control block (DCB) associated with the name of the DD 
statement. Space for a data control block, which specifies the particular data set to be 
used, is reserved by a DCB macro instruction when your program is assembled. 



System/370 provides a variety of devices for collecting, storing, and distributing data. 
Despite the variety, the devices have many common characteristics. The generic term 
volume is used to refer to a standard unit of auxiliary storage. A volume may be a reel of 
magnetic tape, a disk pack, or a drum. 

Each data set stored on a volume has its name, location, organization, and other control 
information stored in the data set label or volume table of contents (for direct-access 
volumes only). Thus, when the name of the data set and the volume on which it is stored 
are made known to the operating system, a complete description of the data set, 
including its location on the volume, can be retrieved. Then, the data itself can be 
retrieved, or new data added to the data set. 

Various groups of labels are used to identify magnetic-tape and direct-access volumes, as 
well as the data sets they contain. Magnetic-tape volumes can have standard or 
nonstandard labels, or they can be unlabeled. Direct-access volumes must use standard 
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labels. Standard labels include a volume label, a data set label for each data set, and 
optional user labels. 

Keeping track of the volume on which a particular data set resides can be a burden and a 
source of error. To alleviate this problem, the system provides for automatic cataloging 
of data sets. The system can retrieve a cataloged data set if given only the name of the 
data set. If the name is qualified, each qualifier corresponds to one of the indexes in the 
catalog. For example, the system finds the data set DEPT58.SMTTH.DATA3 by 
searching a master index to determine the location of the index name DEPT58, by 
searching that index to find the location of the index SMITH, and by searching that 
index for DAT A3 to find the identification of the volume containing the data set. 

By use of the catalog, collections of data sets related by a common external name and 
the time sequence in which they were cataloged (their generation) can be identified; they 
are called generation data groups. For example, a data set name LAB.PAYROLL(O) 
refers to the most recent data set of the group; LAB.PAYROLL(-l) refers to the second 
most recent data set, etc. The same data set names can be used repeatedly with no 
requirement to keep track of the volume serial numbers used. 



Direct-Access Volumes 



Direct-access volumes are used to store executable programs, including the operating 
system itself. Direct-access storage is also used for data and for temporary working 
storage. One direct-access storage volume may be used for many different data sets, and 
space on it may be reallocated and reused. A volume table of contents (VTOC) is used 
to account for each data set and available space on the volume. 

Each direct-access volume is identified by a volume label, which is stored in track of 
cylinder 0. You may specify up to seven additional labels, located after the standard 
volume label, for further identification. 

The VTOC is a data set consisting of data set control blocks (DSCBs) that describe the 
contents of the direct-access volume. The VTOC can contain seven kinds of DSCBs, 
each with a different purpose and a different format number. OS/VS2 System 
Programming Library: Debugging Handbook describes the seven kinds of DSCBs, their 
purposes, and their formats. 

Each direct-access volume is initialized by a utility program before being used on the 
system. The initialization program generates the volume label and constructs the table of 
contents. For additional information on direct-access labels, see "Appendix A: 
Direct- Access Labels." 

When a data set is to be stored on a direct-access volume, you must supply the operating 
system with the amount of space to be allocated to the data set, expressed in blocks, 
tracks, or cylinders. Space allocation can be independent of device type if the request is 
expressed in blocks. If the request is made in tracks or cylinders, you must be aware of 
such device considerations as cylinder capacity and track size. 



Magnetic-Tape Volumes 



Because data sets on magnetic-tape devices must be organized sequentially, the operating 
system does not require space allocation procedures comparable to those for 
direct-access devices. When a new data set is to be placed on a magnetic-tape volume, 
you must specify the data set sequence number if it is not the first data set on the reel. 
The operating system positions a volume with IBM standard labels, American National 
Standard labels, or no labels so that the data set can be read or written. If the data set 
has nonstandard labels, you must provide for volume positioning in your 
nonstandard-label-processing routines. All data sets stored on a given magnetic-tape 
volume must be recorded in the same density. 
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When a data set is to be stored on an unlabeled tape volume and you have not specified a 
volume serial number, the system assigns a serial number to that volume and to any 
additional volumes required for the data set. Each such volume is assigned a serial 
number of the form Lxxxyy where xxx indicates the data set sequence number from IPL 
to IPL and yy indicates the volume sequence number for the data set. If you specify 
volume serial numbers for unlabeled volumes on which a data set is to be stored, the 
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system assigns volume serial numbers to any additional volumes required. If data sets 
residing on unlabeled volumes are to be cataloged or passed, you should specify the 
volume serial numbers for the volumes required. This will prevent data sets residing on 
different volumes from being cataloged or passed under identical volume serial numbers. 
Retrieval of such data sets could result in unpredictable errors. 

Each data set and each data set label group on magnetic tape that is to be processed by 
the operating system must be followed by a tapemark. Tapemarks cannot exist within a 
data set. When the operating system is used to create a tape with standard labels or no 
labels, all tapemarks are automatically written. Two tapemarks are written after the last 
trailer label group on a volume to indicate the last data set on the volume. On an 
unlabeled volume, the two tapemarks are written after the last data set. 

When the operating system is used to create a tape data set with nonstandard labels, the 
delimiting tapemarks are not written. If the data set is to be retrieved by the operating 
system, those tapemarks must be written by your nonstandard-label-processing routine. 
Otherwise, tapemarks are not required after nonstandard labels since positioning of the 
tape volumes must be handled by installation routines. 

For more information on labels for magnetic-tape volumes, refer to OS/VS Tape 
Labels. 

The data on magnetic-tape volumes can be in either EBCDIC or ASCII. ASCII is a 7-bit 
code consisting of 128 characters. It permits data on magnetic tape to be transferred 
from one computer to another even though the two computers may be products of 
different manufacturers. 

Data management support of ASCII and of American National Standard tape labels is 
such that data management can translate records on input tapes in ASCII into EBCDIC 
for internal processing and translate the EBCDIC back into ASCII for output. Records 
on such input tapes may be sorted into ASCII collating sequence. 



Data Set Record Formats 



A data set is composed of a collection of records that normally have some logical relation 
to one another. The record is the basic unit of information used by a processing program. 
It might be a single character, all information resulting from a given business transaction, 
or measurements recorded at a given point in an experiment. Much data processing 
consists of reading, processing, and writing individual records. 

The process of grouping a number of records before writing them on a volume is referred 
to as blocking. A block is made up of the data between interrecord gaps (IRGs). Each 
block can consist of one or more records. Blocking conserves storage space on the 
volume because it reduces the number of IRGs in the data set. In many cases, blocking 
also increases processing efficiency by reducing the number of input/output operations 
required to process a data set. 

Records may be in one of four formats: fixed-length (format-F), variable-length for data 
in EBCDIC (format-V), variable-length for data to be translated to or from ASCII 
(format-D), or undefined-length (format-U). The main consideration in the selection of 
a record format is the nature of the data set itself. You must know the type of input your 
program will receive and the type of output it will produce. Selection of a record format 
is based on this knowledge, as well as on an understanding of the input/output devices 
that are used to contain the data set and the access method used to read and write the 
data records. The record format of a data set is indicated in the data control block 
according to specifications in the DCB macro instruction, the DD statement, or the data 
set label. 

For ASCII tapes, data can be in format-F, format-D, and format-U with the restrictions 
noted under "Fixed-Length Records, ASCII tapes," "Variable-Length 
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Records — Format D," and "Undefined-Length Records." When data management reads 
records from ASCII tapes, it translates the records into EBCDIC. When data 
management writes records onto ASCII tapes, it translates the records into ASCII. 
Because you use input records after they are translated and because output records are 
translated when you ask data management to write them, you work only with EBCDIC. 

Note: There is no minimum requirement for block size; however, if a data check occurs 
on a magnetic-tape device, any block shorter than 12 bytes in a Read operation or 18 
bytes in a Write operation is treated as a noise record and lost. No check for noise is 
made unless a data check occurs. The sort/merge program does not accept physical 
blocks or logical records shorter than 1 8 bytes from any device. 

For the 3800 printer, the data in the record can contain two optional bytes. The optional 
control character used for carriage control, followed by an optional table reference 
character used for dynamically selecting a character arrangement table during printing. 
See the IBM 3800 Printing Subsystem Programmer's Guide for more information on 
the table reference character. 



Fixed-Length Records 



The size of fixed-length (format-F) records, shown in Figure 1 , is constant for all records 
in the data set. The number of records within a block is constant for every block in the 
data set, unless the data set contains truncated (short) blocks. If the data set contains 
unblocked format-F records, one record constitutes one block. 

The system automatically performs physical length checking (except for card readers) on 
blocked or unblocked format-F records. Allowances are made for truncated blocks. 

Format-F records are shown in Figure 1. The optional control character (c), used for 
stacker selection or carriage control, may be included in each record to be printed or 
punched. 



Block 



Block 



Blocked Records 



Record A 


Record B 


Record C 



Record D 


Record E 


Record F 



Block 



Unblocked Records 



Record A 



Block 



Record 



Record B 



v: 



Data 



\ | Optional Control / 
\ Character - 1 Byte / 



\ 



/ 



Record C 



Block 



Record D 



Figure 1. Fixed-Length Records 



22 OS/VS2 MVS Data Management Services Guide 



Fixed-Length Records, Standard Format: During creation of a sequential data set (to be 
processed by BSAM or QSAM) with fixed-length records, the RECFM subparameter of 
the DCB macro instruction may specify a standard format (RECFM=FS or FBS). A 
standard-format data set must conform to the following specifications: 

• All records in the data set are format-F records. 

• No block except the last block is truncated. (With BSAM you must ensure that this 
specification is met.) 

• Every track except the last one contains the same number of blocks. 

• Every track except the last one is filled to capacity as determined by the track capacity 
formula established for the device. (These formulas are presented in Part 3 of this 
book under "Allocating Space on Direct-Access Volumes.") 

• The data set organization is physical-sequential. A member of a partitioned data set 
cannot be specified. 

A sequential data set with fixed-length records having a standard format can be read 
more efficiently than a data set that doesn't specify a standard format. This efficiency is 
possible because the system is able to determine the address of each record to be read 
because each track contains the same number of blocks. 

You should never extend a data set of this type (by coding DISP=MOD) if the last block 
is truncated, because the extension will cause the data set to contain a truncated block 
that isn't the last block. This type of data set on magnetic tape should not be read 
backward, because then the data set would begin with a truncated block. Consequently, 
you probably won't want to use this type of data set with magnetic tape. If you use one 
of the basic access techniques with this type of data set, you should not specify that the 
track overflow feature is to be used with the data set. 

Standard format should not be used to read records from a data set that was created 
using a RECFM other than standard since other record formats may not create the 
precise format required by standard. 

If at any time the characteristics of your data set are altered from the specifications 
described above, then the data set should no longer be processed with the standard 
format specification. 

Fixed-Length Records, ASCII Tapes: For ASCII tapes, format-F records are the same as 
described above, with two exceptions: 

• Control characters, if present, must be American National Standards Institute (ANSI) 
control characters. 

• Records or blocks of records can contain block prefixes. 

Figure 2 shows the format of fixed-length records for ASCII tapes and where control 
characters and block prefixes go if they exist. 

The block prefix can vary in length from to 99 bytes but the length must be constant 
for the data set being processed. For blocked records, the block prefix precedes the first 
logical record. For unblocked records, the block prefix precedes each logical record. 

Using QSAM and BSAM to read records with block prefixes requires that you specify 
the BUFOFF operand in the DCB. When using QSAM, you cannot read the block prefix 
on input. When using BSAM, you must account for the block prefix on both input and 
output. When using either QSAM or BSAM, you must account for the length of the 
block prefix in the BLKSIZE and BUFL operands of the DCB. 
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Figure 2. Fixed-Length Records for ASCII Tapes 



When you use BSAM on output records, the operating system does not recognize a block 
prefix. Therefore, if you want a block prefix, it must be part of your record. Note that 
you cannot include block prefixes in QSAM output records. 

The block prefix can contain any data you want, but you must avoid using data types 
such as binary, packed decimal, and floating-point that cannot be translated into ASCII. 

For more information about control characters, refer to "Control Character" and to 
"Appendix B: Control Characters." 



Variable-Length Records 



The variable-length record formats are format-V and format-D. Format-V records can 
be spanned; that is, records can be larger than the blocksize, as described below. 
Format-D records are used for ASCII tape data sets and cannot be spanned. Figure 3 
shows blocked and unblocked variable-length records without spanning. 

Variable-Length Records — Format V: Format V provides for variable-length records, 
variable-length record segments, each of which describes its own characteristics, and 
variable-length blocks of such records or record segments. Except when variable-length 
track overflow records are specified for volumes on devices with the rotational position 
sensing feature, the control program performs length checking of the block and uses the 
record or segment length information in blocking and deblocking. The first 4 bytes of 
each record, record segment, or block make up a descriptor word containing control 
information. You must allow for these additional 4 bytes in both your input and output 
buffers. 

Block Descriptor Word: A variable-length block consists of a block descriptor word 
(BDW) followed by one or more logical records or record segments. The block 
descriptor word is a 4-byte field that describes the block. The first 2 bytes specify the 
block length (7/') — 4 bytes for the BDW plus the total length of all records or segments 
within the block. This length can be from 8 to 32,760 bytes or, when you are using 
WRITE with tape, from 18 to 32,760. The third and fourth bytes are reserved for future 
system use and must be 0. If the system does your blocking — that is, when you use the 
queued access technique — the operating system automatically provides the BDW when it 
writes the data set. If you do your own blocking — that is, when you use the basic access 
technique — you must supply the BDW. 
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Figure 3. Nonspanned, Variable-Length Records 



Record Descriptor Word: A variable-length logical record consists of a record descriptor 
word (RDW) followed by the data. The record descriptor word is a 4-byte field 
describing the record. The first 2 bytes contain the length (7/') of the logical record 
(including the 4-byte RDW). The length can be from 4 to 32,756. For information about 
processing a sequential data set, see "Data Format — Device Type Considerations." All 
bits of the third and fourth bytes must be 0, as other values are used for spanned records. 
For output, you must provide the RDW except in data mode for spanned records 
(described under "Buffer Control"). For output in data mode, you must provide the total 
data length in the physical record length field (DCBPRECL) of the DCB. For input, the 
operating system provides the RDW except in data mode. In data mode, the system 
passes the record length to your program in the logical record length field (DCBLRECL) 
of the DCB. The optional control character (c) may be specified as the fifth byte of each 
record and must be followed by at least one byte of data (the length in the RDW, in this 
case, would be six). The first byte of data is a table reference character if OPTCD=J has 
been specified. The RDW, the optional control character, and the optional table 
reference character are not punched or printed. 

Spanned Variable-Length Records (Sequential Access Method): The spanning feature of the 
queued and basic sequential access methods enables you to create and process 
variable-length logical records that are larger than one physical block and/ or to pack 
blocks with variable-length records by splitting the records into segments so that they 
can be written into more than one block, as shown in Figure 4. 

When spanning is specified for blocked records, the system tries to fill all blocks. For 
unblocked records, a record larger than blocksize is split and written in two or more 
blocks, each block containing only one record or record segment. Thus the blocksize may 
be set to the one that is best for a given device or processing situation. It is not restricted 
by the maximum record length of a data set. A record may, therefore, span several 
blocks, and may even span volumes. Note that a logical record spanning three or more 
volumes cannot be processed in update mode (described under "Buffer Control") by 
QSAM. A block can contain a combination of records and record segments, but not 
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Figure 4. Spanned Variable-Length Records 



multiple segments of the same record. When records are added to or deleted from a data 
set, or when the data set is processed again with different blocksize or record-size 
parameters, the record segmenting will change. 

Considerations for Processing Spanned Record Data Sets: When spanned records span 
volumes, reading errors may occur when using QSAM if a volume which begins with a 
middle or last segment is mounted first or if an FEOV macro instruction is issued 
followed by another GET. QSAM cannot begin reading from the middle of the record. 
The errors include duplicate records, program checks in the user's program, and invalid 
input from the spanned record data set. 

When a spanned record data set is to be opened in UPDAT mode and QSAM is used, a 
record area must be provided by using the BUILDRCD macro instruction or by 
specifying BFTEK=A in the DCB. 

If you issue the FEOV macro instruction when reading a data set that spans volumes, or 
if a spanned multi volume data set is opened to other than the first volume, make sure 
that each volume begins with the first (or only) segment of a logical record. Input 
routines cannot begin reading in the middle of a logical record. 

Segment Descriptor Word: Each record segment consists of a segment descriptor word 
(SDW) followed by the data. The segment descriptor word, similar to the record 
descriptor word, is a 4-byte field that describes the segment. The first 2 bytes contain the 
length ('//') of the segment, including the 4-byte SDW. The length can be from 5 to 
32,756 bytes or, when you are using WRITE with tape, from 18 to 32,756 bytes. The 
third byte of the SDW contains the segment control code, which specifies the relative 
position of the segment in the logical record. The segment control code is in the 
rightmost 2 bits of the byte. The segment control codes are shown in Figure 5. The 
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remaining bits of the third byte and all of the fourth byte are reserved for future system 
use and must be 0. 

Binary Code Relative Position of Segment 

00 Complete logical record 

01 First segment of a multisegment record 

10 Last segment of a multisegment record 

1 1 Segment of a multisegment record other than the first or last segment 
Figure 5. Segment Control Codes 

The SDW for the first segment replaces the RDW for the record after the record has 
been segmented. You or the operating system can build the SDW, depending on which 
mode of processing is used. In the basic sequential access method, you must create and 
interpret the spanned records yourself. In the queued sequential access method move 
mode, complete logical records, including the RDW, are processed in your work area. 
GET consolidates segments into logical records and creates the RDW. PUT forms 
segments as required and creates the SDW for each segment. Data mode is similar to 
move mode, but allows reference only to the data portion of the logical record in your 
work area. The logical record length is passed to you through the DCBLRECL field of 
the data control block. In locate mode, both GET and PUT process one segment at a 
time. However, in locate mode, if you provide your own record area using the 
BUILDRCD macro instruction or if you ask the system to provide a record area by 
specifying BFTEK=A, then GET, PUT, and PUTX process one logical record at a time. 
(BFTEK=A or the BUILDRCD macro cannot be specified when logical records exceed 
32,760 bytes. To process logical records that exceed 32,760 bytes, you must use locate 
mode and specify LRECL=X in your DCB macro.) 

A logical record spanning three or more volumes cannot be processed when the data set 
is opened for update. 

When unit-record devices are used with spanned records, the system assumes that 
unblocked records are being processed and the block size must be equivalent to the 
length of one print line or one card. Records that span blocks are written one segment at 
a time. 

SYSIN and SYSOUT Restrictions: Spanned variable-length records cannot be specified 
for a SYSIN data set. If you're using QSAM to process a SYSOUT data set, move mode 
(see "Buffer Control") is more efficient than locate mode. 

Null Segments: A 1 in bit position of the SDW indicates a null segment. A null 
segment means that there are no more segments in the block. Bits 1-7 of the SDW and 
the remainder of the block must be binary zeros. A null segment is not an 
end-of-logical-record delimiter. (You do not have to be concerned about null segments 
unless you have created a data set using null segments.) 

Spanned Variable-Length Records (Basic Direct Access Method): The spanning feature of 
the basic direct access method (BDAM) enables you to create and process 
variable-length unblocked logical records that are longer than one track. The feature also 
enables you to pack tracks with variable-length records by splitting the records into 
segments. These segments can then be written onto more than one track, as shown in 
Figure 6. 

When you specify spanned, unblocked record format for the basic direct access method 
and when a complete logical record cannot fit on the track, the system tries to fill the 
track with a record segment. Thus the maximum record length of a data set is not 
restricted by block size. Furthermore, segmenting records allows a record to span several 
tracks, with each segment of the record on a different track. However, since the system 
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Figure 6. Spanned Variable-Length Records for BDAM Data Sets 



does not allow a record to span volumes, all segments of a logical record in a direct data 
set are on the same volume. 

Variable-Length Records — Format D: For ASCII tapes, variable-length records must be 
format-D records. Format-D records are the same as format-V records, except: 

• Control characters, if present, must be ANSI control characters. 

• Records or blocks of records can contain block prefixes. 

Figure 7 shows the format of variable-length records for ASCII tapes, where the record 
descriptor word (RDW) must go, and where block prefixes and control characters can go 
when they exist. 

To specify a block prefix, code the BUFOFF operand in the DCB macro. The block 
prefix can vary in length from to 99 bytes but its length must remain constant for the 
data set being processed. For blocked records, the block prefix precedes the first logical 
record in each block. For unblocked records, the block prefix precedes each logical 
record. If the block prefix exists, it precedes the RDW. 

To specify that the block prefix is to be treated as a BDW by data management for 
format-D records on output, code BUFOFF=L as a DCB operand. Your block prefix 
must be 4 bytes long, and it must contain the length of the block, including the block 
prefix. The maximum length of a format D, BUFOFF=L block is 9999 because the 
length (stated in binary by the user) is translated to a four-byte zoned decimal field on 
the ASCII tape when the tape is written, and is then converted back to a two-byte length 
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Figure 7. Variable-Length Records for ASCII Tapes 



field in binary followed by two bytes of zeros when the block is read. If you use QSAM 
to write records, data management fills in the block prefix for you. If you use BSAM to 
write records, you must fill in the block prefix yourself. If you are using chained 
scheduling to read blocked format-D records, coding BUFOFF =absolute expression in 
the DCB is not allowed. Instead, BUFOFF=L is required, because the access method 
needs binary RDWs and valid end-of-block addresses to unblock the records. 

When using QSAM, you cannot read the block prefix on input. When using BSAM, you 
must account for the block prefix on both input and output. When using either QSAM or 
BSAM, you must account for the length of the block prefix in the BLKSIZE and BUFL 
operands. 

When you use BSAM on output records, the operating system does not recognize the 
block prefix. Therefore, if you want a block prefix, it must be part of your record. 

The block prefix can contain any data you want, but you must avoid using data types, 
such as binary, packed decimal, and, floating-point, that cannot be translated into ASCII. 
For format-D records, the only time the block prefix can contain binary data is when you 
have coded BUFOFF=L, which tells data management that the prefix is a BDW. Unlike 
the block prefix, the RDW must always be in binary. 

If you create variable-length records that are shorter than 18 bytes, data management 
pads each one up to a length of 18 bytes when the records are written onto ASCII tape. 
The padding character used is the ASCII circumflex. 

For more information about control characters, refer to "Control Character" and to 
"Appendix B: Control Characters." 
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Undefined-Length Records 



Format U permits processing of records that do not conform to the F or V format. As 
shown in Figure 8, each block is treated as a record; therefore, deblocking must be 
performed by your program. The optional control character may be used in the first byte 
of each record. Because the system does not perform length checking on format-U 
records, your program may be designed to read less than a complete block into virtual 
storage. 
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Figure 8. Undefined-Length Records 



For ASCII tapes, format-U records are the same as described above, with the two 
exceptions described for format-F records on ASCII tapes. 

Figure 9 shows the format of undefined-length records for ASCII tapes and where a 
control character and block prefix, if any, go. 
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Figure 9. Undefined-Length Records for ASCII Tapes 



For format-U records, the user must specify the record length when issuing the WRITE, 
PUT, or PUTX macro instruction. No length checking is performed by the system, so no 
error indication will be given if the specified length does not match the buffer size or 
physical record size. 

In update mode, you must issue a GET or READ macro before you issue a PUTX or 
WRITE macro to a data set on a direct-access device. If you change the record length 
when you issue the PUTX or WRITE macro, the record will be padded with zeros or 
truncated to match the length of the record received when the GET or READ macro was 
issued. No error indication will be given. 
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Control Character 



You may specify in the DD statement, the DCB macro instruction, or the data set label 
that an optional control character is part of each record in the data set. The 1-byte 
character is used to indicate a carriage control channel when the data set is printed or a 
stacker bin when the data set is punched. Although the character is a part of the record 
in storage, it is never printed or punched. For that reason, buffer areas must be large 
enough to accommodate the character. If the immediate destination of the record is a 
device, such as disk, that does not recognize the control character, the system assumes 
that the control character is the first byte of the data portion of the record. If the 
destination of the record is a printer or punch and you have not indicated the presence of 
a control character, the system regards the control character as the first byte of data. A 
list of the control characters is in "Appendix B: Control Characters." 



3800 Table Reference Character 



The 3800 Table Reference Character is a numeric character (0,1,2, or 3) corresponding 
to the order in which the character arrangement table names have been specified with the 
CHARS keyword. It is used for selection of a character arrangement table during 
printing. See IBM 3800 Printing Subsystem Programmer's Guide for more 
information on the table reference character. 



Direct-Access Device Characteristics 



Regardless of organization, data sets created using the operating system can be stored on 
a direct-access volume. Each block of data has a distinct location and a unique address, 
making it possible to locate any record without extensive searching. Thus, records can be 
stored and retrieved either directly or sequentially. 

Although direct-access devices differ in physical appearance, capacity, and speed, they 
are similar in data recording, data checking, data format, and programming. The 
recording surface of each volume is divided into many concentric tracks. The number of 
tracks and their capacity vary with the device. Each device has some type of access 
mechanism, containing read/write heads that transfer data as the recording surface 
rotates past them. Only one head at a time can transfer data. 

The logical arrangement of related tracks is vertical rather than horizontal. As shown in 
Figure 10, a cylinder of a 2316 disk pack is composed of 20 tracks, one for each 
recording surface. Because there are 203 tracks per recording surface, there are 203 
vertical cylinders of 20 tracks each. If a data set extends to more than 1 track, it is 
continued on the next track in the cylinder, not the next track on the same recording 
surface. 
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Track Format 



Information is recorded on all direct-access volumes in a standard format. In addition to 
device data, each track contains a track descriptor record {capacity record or R0) and 
data records. 

As shown in Figure 1 1 , there are two possible data record formats — count-data and 
count-key-data — only one of which can be used for a particular data set. 

In addition to device data, the count area contains 8 bytes that identify the location of 
the record by cylinder, head, and record numbers, its key length (0 if no keys are used), 
and its data length. 
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Figure 11. Direct-Access Volume Track Formats 
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Track Addressing 



If the records are written with keys, the key area (1 to 255 bytes) contains a record key 
that specifies the data record by part number, account number, sequence number, or 
some other identifier. In some cases, records are written with keys so that they can be 
located quickly. 



Two types of addresses can be used to store and retrieve data on a direct-access volume: 
actual addresses and relative addresses. The only advantage of using actual addresses is 
the elimination of time required to convert from relative to actual addresses and vice 
versa. When sequentially processing a multiple-volume data set, you can refer only to 
records of the current volume. 

Actual Addresses: When the system returns the actual address of a record on a 
direct-access volume to your program, it is in the form MBBCCHHR, where: 

M 

is a 1-byte binary number specifying the relative location of an entry in a data extent 
block (DEB). The data extent block is created by the system when the data set is 
opened. Each extent entry describes a set of consecutive tracks allocated for the data 
set. 

BBCCHH 

is three 2-byte binary numbers specifying the cell (bin), cylinder, and head number for 
the record (its track address). The cylinder and head numbers are recorded in the 
count area for each record. 

R 

is a 1-byte binary number specifying the relative block number on the track. The 
block number is also recorded in the count area. 

If you use actual addresses in your program, the data set must be treated as unmovable. 

Relative Addresses: Two kinds of relative addresses can be used to refer to records in a 
direct-access data set: relative block addresses and relative track addresses. 

The relative block address is a 3 -byte binary number that indicates the position of the 
block relative to the first block of the data set. Allocation of noncontinuous sets of 
blocks does not affect the number. The first block of a data set always has a relative 
block address of 0. 

The relative track address has the form TTR, where: 

TT 

is a 2-byte binary number specifying the position of the track relative to the first track 
allocated for the data set. The TT for the first track is 0. Allocation of noncontinuous 
sets of tracks does not affect the number. 



R 



is a 1-byte binary number specifying the number of the block relative to the first block 
on the track TT. The R value for the first block of data on a track is 1. 
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Track Overflow 



If the record overflow feature is available for the direct-access device being used, you 
can reduce the amount of unused space on the volume by specifying the track overflow 
option in the DD statement or the DCB macro instruction associated with the data set. If 
the option is used, a block that does not fit on the track is partially written on that track 
and continued on the next track. (The track onto which the record is continued must be 
physically next and must be part of the same extent as the track that holds the first part 
of the record.) Each segment (the portion written on one track) of an overflow block has 
a count area. The data length field in the count area specifies the length of that segment 
only. If the block is written with a key, there is only one key area for the block. It is 
written with the first segment. If the track overflow option is not used, blocks are not 
split between tracks. 



Write-Validity-Check Option 



You can specify the write-validity-check option in either the DD statement or the DCB 
macro instruction. After a record is transferred from main to secondary storage, the 
system reads the stored record (without data transfer) and, by testing for a data check 
from the I/O device, verifies that the record was written correctly. This verification 
requires an additional revolution of the device for each record that was written. Standard 
error recovery procedures are initiated if an error condition is detected. 



The Data Control Block 



You must describe the characteristics of a data set, the volume on which it resides, and 
its processing requirements before processing can begin. During execution, the 
descriptive information is made available to the operating system in the data control 
block (DCB). A DCB is required for each data set and is created in a processing 
program by a DCB macro instruction. 

Primary sources of information to be placed in the data control block are a DCB macro 
instruction, a data definition (DD) statement, and a data set label. In addition, you can 
provide or modify some of the information during execution by storing the pertinent data 
in the appropriate field of the data control block. The specifications needed for 
input/output operations are supplied during the initialization procedures of the OPEN 
macro instruction. Therefore, the pertinent data can be provided when your job is to be 
executed rather than when you write your program (see Figure 12). 
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Figure 12. Completing the Data Control Block 
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When the OPEN macro instruction is executed, the Open routine: 

• Completes the data control block 

• Loads all necessary access method routines not already in virtual storage 

• Initializes data sets by reading or writing labels and control information 

• Constructs the necessary system control blocks 

Information from a DD statement is stored in the job file control block (JFCB) by the 
operating system. When the job is to be executed, the JFCB is made available to the 
open routine. The data control block is filled in with information from the DCB macro 
instruction, the JFCB, or an existing data set label. If more than one source specifies 
information for a particular field, only one source is used. A DD statement takes 
precedence over a data set label, and a DCB macro instruction over both. However, you 
can modify most data control block fields either before the data set is opened or when 
the operating system returns control to your program (at the data control block open 
exit). Some fields can be modified during processing. 

Figure 13 illustrates the process and the sequence of filling in the data control block from 
various sources. The primary source is your program, that is, the DCB macro instruction. 
In general, you should use only those DCB parameters that are needed to ensure correct 
processing. The other parameters can be filled in when your program is to be executed. 
When a direct-access data set is opened (or a magnetic tape with standard labels is 
opened for INPUT, RDBACK, or INOUT), any field in the JFCB not completed by a 
DD statement is filled in from the data set label (if one exists). When opening a magnetic 
tape for output, the tape label is assumed not to exist or to apply to the current data set 
unless you specify DISP=MOD and a volume serial number in the volume parameter of 
the DD statement. Any field not completed in the DCB is filled in from the JFCB. Fields 
in the DCB can then be completed or modified by your own DCB exit routine. Then all 
DCB fields are unconditionally merged into corresponding JFCB fields if your data set is 
opened for output. This is done by specifying OUTPUT, OUTIN, EXTEND, or 
OUTINX in the OPEN macro instruction. The DSORG field is not merged unless this 
field contains zeros in the JFCB. If your data set is opened for input (INPUT, INOUT, 
RDBACK, or UPDAT is specified in the OPEN macro instruction), the DCB fields are 
not merged unless the corresponding JFCB fields contain zeros. 

When the data set is closed, the data control block is restored to the condition it had 
before the data set was opened (the buffer pool is not freed). The open and close 
routines also use the updated JFCB to write the data set labels for output data sets. If the 
data set is not closed when your program terminates, the operating system will close it 
automatically. 



Data Set Description 



For each data set you are going to process, there must be a corresponding DCB and DD 
statement. The characteristics of the data set and device-dependent information can be 
supplied by either source. In addition, the DD statement must supply data set 
identification, device characteristics, space allocation requests, and related information as 
specified in OS/VS2 JCL. You establish the logical connection between a DCB and a 
DD statement by specifying the name of the DD statement in the DDNAME field of the 
DCB macro instruction, or by completing the field yourself before opening the data set. 

Once the data set characteristics have been specified in the DCB macro instruction, they 
can be changed only by modification of the DCB during execution. The fields of the 
DCB discussed below are common to most data organizations and access techniques. 



Part 1: Introduction to Data Management 35 



Page of GC26-3875-0 
Revised August 31, 1978 
ByTNLGN26-0915 




/T) — >" Control -< — (T\ 
v ' Block V_y 



DCB 

Exit 

Routine 



DD 
Statement 



©r* 



Job File 

Control 

Block 



e 



New 

Data Set 

Label 



Old 

Data Set 

Label 



Figure 13. Sources and Sequence of Operations for Completing the Data Control Block 

Data Set Organization (DSORG): specifies the organization of the data set as physical 
sequential (PS), indexed sequential (IS), partitioned (PO), or direct (DA). If the data set 
contains absolute rather than relative addresses, you must mark it as unmovable by 
adding a U to the DSORG parameter (for example, by coding DSORG=PSU). You must 
specify the data set organization in the DCB macro instruction. When creating or 
processing an indexed sequential organization data set or creating a direct data set, you 
must also specify DSORG in the DD statement. When creating a direct data set, the 
DSORG in the DCB macro must specify PS or PSU and the DD statement must specify 
DA or DAU. 

Record Format (RECFM): specifies the characteristics of the records in the data set as 
fixed-length (F), variable-length (V), or undefined-length (U). Blocked records are 
specified as FB or VB. You may also specify the records as fixed-length standard by 
using FS or FBS. You can request track overflow for records other than standard format 
by adding a T to the RECFM parameter (for example, by coding FBT). 

Record Length (LRECL): specifies the length, in bytes, of each record in the data set. If 
the records are of variable length, the maximum record length must be specified. For 
input, the field should be omitted for format-U records. 

Blocksize (BLKSIZE): specifies the maximum length, in bytes, of a block. If the records 
are of format F, the blocksize must be an integral multiple of the record length except for 
SYSOUT data sets. (See "Routing Data Through the System Input and Output Streams" 
in Part 3 of this book.) If the records are of format V, the blocksize specified must be the 
maximum blocksize. If records are unblocked, the blocksize must be 4 bytes greater than 
the record length (LRECL). When spanned variable-length records are specified, the 
blocksize is independent of the record length. 

Key Length (KEYLEN): specifies the length (0-255) in bytes of an optional key which 
precedes each block on a direct-access device. The value of KEYLEN is not included in 
BLKSIZE or LRECL but must be included in BUFL if buffer length is specified. Thus, 
BUFL=KEYLEN+BLKSIZE. 
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Each of the data set description fields of the data control block, except as noted for data 
set organization, can be specified when your job is to be executed. In addition, data set 
identification and disposition, as well as device characteristics, can be specified at that 
time. The parameters of the DD statement discussed below are common to most data set 
organizations and devices. 
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Data Definition Name (DDNAME): is the name of the DD statement and connects the 
DD statement to the data control block that specifies the same DDNAME. 

Data Set Name (DSNAME): specifies the name of a newly defined data set, or refers to 
a previously defined data set. 

Data Control Block (DCB): provides, by means of subparameters, information to be used 
to complete those fields of the data control block that were not specified in the DCB 
macro instruction. This parameter cannot be used to modify a data control block. 

Channel Separation and Affinity (SEP/AFF): requests that specified data sets use 
different channels during input/output operations. 

Input/Output Device (UNIT): specifies the number and type of I/O devices to be 
allocated for use by the data set. 

Space Allocation (SPACE): designates the amount of space on a direct-access volume 
that should be allocated for the data set. Unused space can be released when your job is 
finished. 

Volume Identification (VOLUME): identifies the particular volume or volumes, or the 
number of volumes, to be assigned to the data set, or the volumes on which existing data 
sets reside. 

Data Set Label (LABEL): indicates the type and contents of the label or labels 
associated with the data set. The operating system verifies standard labels. Standard 
labels include those specified in the DD statement as SL (standard labels), SUL 
(standard user labels), AL (American National Standard labels), and AUL (American 
National Standard user labels). Nonstandard labels (NSL) can be specified only if your 
installation has incorporated into the operating system routines to write and process 
nonstandard labels. 

Data Set Disposition (DISP): describes the status of a data set and indicates what is to be 
done with it at the end of the job step. 



Processing Program Description 



The operating system requires several types of processing information to ensure proper 
control of your input/output operations. The forms of macro instructions in the program, 
buffering requirements, and the addresses of your special processing routines must be 
specified during either the assembly or the execution of your program. The DCB 
parameters specifying buffer requirements are discussed in "Buffer Acquisition and 
Control." 

Because macro instructions are expanded during the assembly of your program, you must 
supply the macro instruction forms that are to be used in processing each data set in the 
associated DCB macro instruction. You can supply buffering requirements and related 
information in the DCB macro instruction, the DD statement, or by storing the pertinent 
data in the appropriate field of the data control block before the end of your DCB exit 
routine. If the addresses of special processing routines are omitted from the DCB macro 
instruction, you must complete them in the DCB before opening the data set. 



Macro Instruction Form (MACRF) 



The MACRF parameter of the DCB macro instruction specifies not only the macro 
instructions used in your program, but also the processing mode as discussed in the 
section "Buffer Control." The organization of your data set, the macro instruction form, 
and the processing mode determine which of the data access routines will be used during 
execution. 
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Exits to Special Processing Routines 

The DCB macro instruction can be used to identify the location of: 

• A routine that performs end-of-data procedures 

• A routine that supplements the operating system's error recovery routine 

• A list that contains addresses of special exit routines 

The exit addresses can be specified in the DCB macro instruction or you can complete 
the DCB fields before opening the data set. Figure 14 summarizes the exits that you can 
specify either explicitly in the DCB, or implicitly by specifying the address of an exit list 
in the DCB. 
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Figure 14. Data Management Exit Routines 



End-of-Data-Set Exit Routine (EODAD): The EODAD parameter of the DCB macro 
instruction specifies the address of your end-of-data routine, which may perform any 
final processing on an input data set. This routine is entered when an FEOV macro is 
issued or when a CHECK or GET macro is issued and there are no more records or 
blocks to be retrieved. (On a READ request, this routine is entered when you issue a 
CHECK macro instruction to check for completion of the read operation. For a BSAM 
data set that is opened for UPDAT, this routine is entered at the end of each volume. 
This allows you to issue WRITE macros before an FEOV macro is issued.) 

The EODAD routine is not a subroutine, but rather a continuation of the routine which 
issued the CHECK, GET, or FEOV macro instruction. Once in your EODAD routine, 
you can continue normal processing, such as reposition and resume processing of the 
data set, close the data set, or process another data set. 

For BSAM, you must first reposition the data set that reached end-of-data if you wish to 
issue a BSP, READ, or WRITE macro instruction. You can reposition your data set by 
issuing a CLOSE TYPE=T macro instruction. If a READ macro is issued before the 
data set is repositioned, unpredictable results will occur. 
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For BPAM, you may reposition the data set by issuing a FIND or POINT macro 
instruction. (CLOSE TYPE=T with BPAM results in a no operation performed.) 

For QISAM, you can continue processing the input data set that reached end-of-data by 
first issuing an ESETL macro to end the sequential retrieval, then issuing a SETL macro 
to set the lower limit of sequential retrieval. You can then issue GET macros to the data 
set. 

Your task will be abnormally terminated under either of the following conditions: 

• No exit routine is provided. 

• A GET macro instruction is issued in the EODAD routine to the DCB which caused 
this routine to be entered (unless the access method is QISAM). 

When control is passed to the EODAD routine, the registers contain the following 
information: 

Register Contents 

0-1 Reserved 

2-13 Contents before execution of CHECK, GET, or FEOV macro instruction 

14 Address of the instruction after the last issued GET, CHECK, or FEOV macro instruction 

15 Reserved 

Synchronous Error Routine Exit (SYNAD): The SYNAD parameter of the DCB macro 
instruction specifies the address of an error routine that is to be given control when an 
input/output error occurs. This routine can be used to analyze exceptional conditions or 
uncorrectable errors. The block being read or written can be accepted or skipped, or 
processing can be terminated. 

If an input/output error occurs during data transmission, standard error recovery 
procedures, provided by the operating system, attempt to correct the error before 
returning control to your program. An uncorrectable error usually causes an abnormal 
termination of the task. However, if you specify in the DCB macro instruction the 
address of an error analysis routine (called a SYNAD routine), the routine is given 
control in the event of an uncorrectable error. 

You can write a SYNAD routine to determine the cause and type of error that occurred 
by examining: 

• The contents of the general registers 

• The data event control block (discussed in Part 2 under "Basic Access Technique") 

• The exceptional condition code 

• The standard status and sense indicators 

You can use the SYNAD AF macro instruction to perform this analysis automatically. 
This macro instruction produces an error message that can be printed by a subsequent 
PUT or WRITE macro instruction. 

After completing the analysis, you can return control to the operating system or close the 
data set. If you close the data set, note that you may not use the temporary close 
(CLOSE TYPE=T) option in the SYNAD routine. To continue processing the same data 
set, you must first return control to the control program by a RETURN macro 
instruction. The control program then transfers control to your processing program, 
subject to the conditions described below. In no case should you attempt to reread or 
rewrite the record, because the system has already attempted to recover from the error. 
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When you are using GET and PUT to process a sequential data set, the operating system 
provides three automatic error options (EROPT) to be used if there is no SYNAD 
routine or if you want to return control to your program from the SYNAD routine: 

• ACC accept the erroneous block 

• SKP skip the erroneous block 

• ABE abnormally terminate the task 

These options are applicable only to data errors, as control errors result in abnormal 
termination of the task. Data errors affect only the validity of a block of data. Control 
errors affect information or operations necessary for continued processing of the data 
set. These options are not applicable to output errors, except output errors on the printer. 
If the EROPT and SYNAD fields are not completed, ABE is assumed. 

Since EROPT applies to a physical block of data, and not to a logical record, use of SKP 
or ACC may result in incorrect assembly of spanned records. 

When you use READ and WRITE macro instructions, errors are detected when you 
issue a CHECK macro instruction. If you are processing a direct or sequential data set 
and you return to the control program from your SYNAD routine, the operating system 
assumes that you have accepted the bad record. If you are creating a direct data set and 
you return to the control program from your SYNAD routine, your task is abnormally 
terminated. In the case of processing a direct data set, the return should be made to the 
control program via register 14 in order to make a control block (the IOB) available for 
reuse in a subsequent READ or WRITE macro instruction. 

For a detailed description of the register contents upon entry to your SYNAD routine, 
refer to the tables in OS/VS2 MVS Data Management Macro Instructions. The tables 
there describe register contents for programs using QISAM, BISAM, BDAM, BPAM, 
BSAM, and QSAM. 

Your SYNAD routine can end by branching to another routine in your program, such as 
a routine that closes the data set. It can also end by returning control to the control 
program, which then returns control to the next sequential instruction (after the macro) 
in your program. If your routine returns control, the conventions for saving and restoring 
register contents are as follows: 

• The SYNAD routine must preserve the contents of registers 13 and 14. If required by 
the logic of your program, the routine must also preserve the contents of registers 2 
through 12. Upon return to your program, the contents of registers 2 through 12 will 
be the same as upon return to the control program from the SYNAD routine. 

• The SYNAD routine must not use the save area whose address is in register 13, 
because this area is used by the control program. If the routine saves and restores 
register contents, it must provide its own save area. 

• If the SYNAD routine calls another routine or issues supervisor or data management 
macro instructions, it must provide its own save area or issue a SYNAD AF macro 
instruction. The SYNADAF macro instruction provides a save area for its own use, 
and then makes this area available to the SYNAD routine. Such a save area must be 
removed from the save area chain by a SYNADRLS macro instruction before control 
is returned to the control program. 
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When you use QSAM to read and translate paper-tape characters, your SYNAD routine 
receives control when you request the record preceding the record in error. Before giving 
control to your SYNAD routine, the system translates the requested record into your 
buffer. 

For example, suppose that you are using QSAM to read and translate a paper-tape data 
set and that you have specified, in your DCB, SYNAD = (address) and EROPT=ACC. 
Suppose also that the third record of the data set has a parity error. When you issue a 
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GET request for the second record, the system translates that record into your buffer 
and, as a result of the error in the third record, passes control to your SYNAD routine. 
Because you specified the accept option, the system returns control to your program 
after your SYNAD error analysis routine completes its processing. When you issue a 
GET request for the third record, all characters other than the erroneous one are 
translated into your buffer; the erroneous character is moved, in normal sequence, into 
your buffer without translation. 

If the error analysis routine receives control from the Close routine when indexed 
sequential data sets are being created (the DCB is opened for QISAM load mode), bit 3 
of the IOBFLAGS field in the load mode buffer control table (IOBBCT) is set to one. 
The DCBWKPT6 field in the DCB contains an address of a list of work area pointers 
(ISLVPTRS). The pointer to the IOBBCT is at offset 8 in this list as shown in the 
following diagram: 



DCB 



248 



Work Area 

Pointers 

(ISLVPTRS) 




IOBBCT 




j L 1 



IOBFLAGS 



If the error analysis routine receives control from the Close routine when indexed 
sequential data sets are being processed using QISAM scan mode, bit 2 of the DCB field 
DCBEXCD2 is set to one. 

Exit List (EXLST): The EXLST parameter of the DCB macro instruction specifies the 
address of a list that contains the addresses of special processing routines, a forms 
control buffer (FCB) image, or a user totaling area. An exit list must be created if user 
label, data control block, end-of-volume, block count, JFCBE, or DCB ABEND exits are 
used, or if a PDAB macro or FCB image is defined in the processing program. 

The exit list is constructed of 4-byte entries that must be aligned on fullword boundaries. 
Each exit list entry is identified by a code in the high-order byte, and the address of the 
routine, image, or area is specified in the 3 low-order bytes. Codes and addresses for the 
exit list entries are shown in Figure 15. 

You can activate or deactivate any entry in the list by placing the required code in the 
high-order byte. Care must be taken, however, not to destroy the last entry indication. 
The operating system routines scan the list from top to bottom, and the first active entry 
found with the proper code is selected. 

You can shorten the list during execution by setting the high-order bit to 1 , and extend it 
by setting the high-order bit to 0. 

When control is passed to an exit routine, the registers contain the following information: 
Register Contents 

Variable; see exit routine description. 

1 The three, low-order bytes contain the address of DCB currently being processed, except 
when user-label exits (X'01'-'u4'), user totaling exit (X'OA'), or DCB ABEND exit (X'l 1') is 
taken, when register 1 contains the address of a parameter list. The contents of the 
parameter list are described in each exit routine description. 

2-13 Contents before execution of the macro instruction. 

14 Return address (must not be altered by the exit routine). 

15 Address of exit routine entry point. 
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Entry Type 


Hexadecimal 
Code 


Inactive entry 


00 


Input header label exit 


01 


Output header label exit 


02 


Input trailer label exit 


03 


Output trailer label exit 


04 


Data control block exit 


05 


End-of-volume exit 


06 


JFCB exit 


07 




08-09 


JFCB exit 


07 




08-09 


User totaling area 


0A 


Block count exit 


0B 


Defer input trailer 
label 


OC 


Defer nonstandard 
input trailer label 


0D 




0E-0F 


FCB image 


10 


DCB ABEND exit 


11 



QSAM parallel input 



JFCBE exit 



Last entry 



12 

13-14 
15 

16-7F 
80 



3-byte Address — Purpose 

Ignore the entry; it is not active. 

Process a user input header label. 

Create a user output header label. 

Process a user input trailer label. 

Create a user output trailer label. 

Take a data control block exit. 

Take an end-of-volume exit. 

JFCB address for RDJFCB and 
OPEN TYPE=J SVCs. 

Reserved for future use 

JFCB address for RDJFCB and OPEN 
TYPE=J SVCs. 

Reserved for future use 

Address of beginning of user's totaling area. 

Take a block-count-unequal exit. 

Defer processing of a user input trailer label 
from end-of-data until closing. 

Defer processing a nonstandard input 
trailer labelmagnetic tape unit from 
end-of-data until closing (no exit routine 
address). 

Reserved for future use 

Define an FCB image. 

Examine the ABEND condition and select 
one of several options. 

Address of the PDAB for which this DCB 
is a member. 

Reserved for future use 

Take an exit during open to allow user to 
examine JCL=specified setup requirements 
for a 3800 printer. 

Reserved for future use 

Treat this entry as last entry in list. 
This code can be specified with any of the 
above but must always be specified 
with the las entry. 



Figure 15. Format and Contents of an Exit List 



The conventions for saving and restoring register contents are as follows: 

• The exit routine must preserve the contents of register 14. It need not preserve the 
contents of other registers. The control program restores the contents of registers 2-13 
before returning control to your program. 

• The exit routine must not use the save area whose address is in register 13, because 
this area is used by the control program. If the exit routine calls another routine or 
issues supervisor or data management macro instructions, it must provide the address 
of a new save area in register 13. 
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Standard User Label Exit: When you create a data set with physical sequential or direct 
organization, you can provide routines to create your own data set labels. You can also 
provide routines to verify these labels when you use the data set as input. Each label is 
80 characters long with the first 4 characters UHL1,UHL2,...,UHL8 for a header label 
or UTL1,UTL2,...,UTL8 for a trailer label. User labels are not allowed on indexed 
sequential data sets. 

The physical location of the labels on the data set depends on the data set organization. 
For direct (BDAM) data sets, user labels are placed on a separate user label track in the 
first volume. User label exits are taken only during execution of the open and close 
routines. Thus you may create or examine up to eight user header labels only during 
execution of open and up to eight trailer labels only during execution of close. Since the 
trailer labels are on the same track as the header labels, the first volume of the data set 
must be mounted when the data set is closed. 

For physical sequential (BSAM or QSAM) data sets, you may create or examine up to 
eight header labels and eight trailer labels on each volume of the data set. For ASCII 
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tape data sets, you may create an unlimited number of user header and trailer labels. The 
user label exits are taken during open, close, and end-of-volume processing. 

To create or verify labels, you must specify the addresses of your label exit routines in an 
exit list as shown in Figure 15. Thus you may have separate routines for creating or 
verifying header and trailer label groups. Care must be taken if a magnetic tape is read 
backward, since the trailer label group is processed as header labels and the header label 
group is processed as trailer labels. 

When your routine receives control, the contents of register are unpredictable. 
Register 1 contains the address of a parameter list. The contents of registers 2-13 are the 
same as when the macro instruction was issued. However, if your program does not issue 
the CLOSE macro instruction, or abnormally terminates before issuing CLOSE, the 
CLOSE macro instruction will be issued by the control program, with control-program 
information in these registers. 

The parameter list pointed to by register 1 is a 16-byte area aligned on a fullword 
boundary. Figure 1 6 shows the contents of the area. 




Address of 80-byte buffer area 

' i 



Address of DCB being processed 
I I 



Address of status information 



Address of user totaling image area 



Figure 16. Parameter List Passed to User Label Exit Routine 



The first address in the parameter list points to an 80-byte label buffer area. For input, 
the control program reads a user label into this area before passing control to the label 
routine. For output, the user label exit routine constructs labels in this area and returns to 
the control program, which writes the label. When an input trailer label routine receives 
control, the EOF flag (high-order byte of the second entry in the parameter list) is set as 
follows: 

bit = 0: Entered at end-of-volume 
bit = 1 : Entered at end-of-f ile 
bits 1-7: Reserved 

When a user label exit routine receives control after an uncorrectable I/O error has 
occurred, the third entry of the parameter list contains the address of the standard status 
information. The error flag (high-order byte of the third entry in the parameter list) is set 
as follows: 

bit = 1 : Uncorrectable I/O error 

bit 1 = 1: Error occurred during writing of updated label 

bits 2-7: Reserved 

The fourth entry in the parameter list is the address of the User totaling image area. This 
image area is the entry in the user totaling save area that corresponds to the last record 
physically written on the volume. The image area is discussed further under "User 
Totaling." 
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Each routine must create or verify one label of a header or trailer label group, place a 
return code in register 15, and return control to the operating system. The operating 
system responds to the decimal return code as shown in Figure 17. 

Routine Type Return Code System Response 

Input header Normal processing is resumed. If there are any remaining labels 

or in the label group, they are ignored, 

trailer label 

4 The next user label is read into the label buffer area and control is 

returned to the exit routine. If there are no more labels in the label 
group, normal processing is resumed. 

8 1 The label is written from the label buffer area and normal processing is 

resumed. 

12 1 The label is written from the label area, the next label is read into the 

label buffer area, and control is returned to the label processing 
routine. If there are no more labels, processing is resumed. 

Output header Normal processing is resumed; no label is written from the label 

or trailer label buffer area. 

4 User label is written from the label buffer area. Normal processing is 

resumed. 

8 User label is written from the label buffer area. If fewer than eight 

labels have been created, control is returned to the exit routine, which 
then creates the next label. If eight labels have been created, normal 
processing is resumed. 

1 Your input label routines can only return these codes when you are processing a physical sequential data set opened for 
UPDAT or a direct data set opened for OUTPUT or UPDAT. These return codes allow you to verify the existing labels, 
update them if necessary, then request that the system write the updated labels. 

Figure 17. System Response to a User Label Exit Routine Return Code 

You can create user labels only for data sets on magnetic-tape volumes with IBM 
standard labels or American National Standard labels and for data sets on direct-access 
volumes. When you specify both user labels and IBM standard labels in a DD statement 
by specifying LABEL=(,SUL) and there is an active entry in the exit list, a label exit 
is always taken. Thus, a label exit is taken even when an input data set does not contain 
user labels, or when no user label track has been allocated for writing labels on a direct- 
access volume. In either case, the appropriate exit routine is entered with the buffer 
area address parameter set to 0. On return from the exit routine, normal processing 
is resumed; no return code is necessary. 

Label exits are not taken for system output (SYSOUT) data sets, or for data sets on 
volumes that do not have standard labels. For other data sets, exits are taken as follows: 

• When an input data set is opened, the input header label exit 01 is taken. If the data 
set is on tape being opened for RDBACK, user trailer labels will be processed. 

• When an output data set is opened, the output header label exit 02 is taken. However, 
if the data set already exists and DISP=MOD is coded in the DD statement, the input 
trailer label exit 03 is taken to process any existing trailer labels. If the input trailer 
label exit 03 does not exist, then the deferred input trailer label exit 0C is taken if it 
exists; otherwise, no label exit is taken. For tape, these trailer labels will be 
overwritten by the new output data or by EOV or close processing when writing new 
standard trailer labels. For direct-access devices, these trailer labels will still exist 
unless rewritten by EOV or close processing in an output trailer label exit. 
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When an input data set reaches end-of-volume, the input trailer label exit 
03 is taken. If the data set is on tape opened for RDBACK, header labels 
will be processed. The input trailer label exit 03 is not taken if you issue an 
FEOV macro instruction. If a defer input trailer label exit 0C is present, 
and an input trailer label exit 03 is not present, the 0C exit is taken. 
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After switching volumes, the input header label exit 01 is taken. If the data set 
is on tape opened for RDBACK, trailer labels will be processed. 

• When an output data set reaches end-of-volume, the output trailer label exit 04 is 
taken. After switching volumes, output header label exit 02 is taken. 

• When an input data set reaches end-of-data, the input trailer label exit 03 is taken 
before the EODAD exit, unless the DCB exit list contains a defer input trailer label 
exit OC. 

• When an input data set is closed, no exit is taken unless the data set was previously 
read to end-of-data and the defer input trailer label exit OC is present. If so, the defer 
input trailer label exit OC is taken to process trailer labels, or if the tape is opened for 
RDBACK, header labels. 

• When an output data set is closed, the output trailer label exit 04 is taken. 

To process records in reverse order, a data set on magnetic tape can be read backward. 
When you read backward, header label exits are taken to process trailer labels, and trailer 
label exits are taken to process header labels. The system presents labels from a label 
group in ascending order by label number, which is the order in which the labels were 
created. If necessary, an exit routine can determine label type (UHL or UTL) and 
number by examining the first four characters of each label. Tapes with IBM standard 
labels and direct-access devices can have as many as eight user labels. Tapes with 
American National Standard labels can have unlimited user labels. 

If an uncorrectable error occurs during reading or writing of a user label, the system 
passes control to the appropriate exit routine with the third word of the parameter list 
flagged and pointing to status information. 

After an input error, the exit routine must return control with an appropriate return code 
(0 or 4). No return code is required after an output error. If an output error occurs while 
the system is opening a data set, the data set is not opened (DCB is flagged) and control 
is returned to your program. If an output error occurs at any other time, the system 
attempts to resume normal processing. 

User Totaling (BSAM and QSAM only): When creating or processing a data set with user 
labels, you may develop control totals for each volume of the data set and store this 
information in your user labels. For example, a control total that was accumulated as the 
data set was created can be stored in your user label and later compared with a total 
accumulated during processing of the volume. User totaling assists you by synchronizing 
the control data you create with records physically written on a volume. For an output 
data set without user labels, you can also develop a control total that will be available to 
your end-of-volume routine. 

To request user totaling, you must specify OPTCD=T in the DCB macro instruction or 
in the DCB parameter of the DD statement. The area in which you accumulate the 
control data (the user totaling area) must be identified to the control program by an 
entry of hexadecimal 0A in the DCB exit list. OPTCD=T cannot be specified for SYSIN 
or SYSOUT data sets. 

The user totaling area, an area in storage that you provide, must begin on a halfword 
boundary and be large enough to contain your accumulated data plus a 2-byte length 
field. Tlie length field must be the first 2 bytes of the area and specify the length of the 
entire area. A data set for which you have specified user totaling (OPTCD=T) will not 
be opened if either the totaling area length or the address in the exit list is 0, or if there is 
no X'OA' entry in the exit list. 

The control program establishes a user totaling save area, in which the control program 
preserves an image of your totaling area, when an I/O operation is scheduled. When the 
output user label exits are taken, the address of the save area entry (user totaling image 
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area) corresponding to the last record physically written on a volume is passed to you in 
the fourth entry of the user label parameter list. This parameter list is described in the 
section "Standard User Label Exit." When an end-of- volume exit is taken for an output 
data set and user totaling has been specified, the address of the user totaling image area 
is in register 0. 

When using user totaling for an output data set, that is, when creating the data set, you 
must update your control data in your totaling area before issuing a PUT or a WRITE 
macro instruction. The control program places an image of your totaling area in the user 
totaling save area when an I/O operation is scheduled. A pointer to the save area entry 
(user totaling image area) corresponding to the last record physically written on the 
volume, is passed to you in your label processing routine. Thus you can include the 
control total in your user labels. When subsequently using this data set for input, you can 
accumulate the same information as you read each record and compare this total with the 
one previously stored in the user trailer label. If you have stored the total from the 
preceding volume in the user header label of the current volume, you can process each 
volume of a multivolume data set independently and still maintain this system of control. 

When variable-length records are specified with the totaling facility for user labels, 
special considerations are necessary. Since the control program determines whether a 
variable-length record will fit in a buffer after a PUT or a WRITE has been issued, the 
total you have accumulated may include one more record than is actually written on the 
volume. In the case of variable-length spanned records, the accumulated total will include 
the control data from the volume-spanning record although only a segment of the record 
is on that volume. However, when you process such a data set, the volume-spanning 
record or the first record on the next volume will not be available to you until after the 
volume switch and user label processing are completed. Thus the totaling information in 
the user label may not agree with that developed during processing of the volume. 

One way you can resolve this situation is to maintain, when you are creating a data set, 
control data pertaining to each of the last two records and include both totals in your 
user labels. Then the total related to the last complete record on the volume and the 
volume-spanning record or the first record on the next volume would be available to your 
user label routines. During subsequent processing of the data set, your user label routines 
can determine if there is agreement between the generated information and one of the 
two totals previously saved. 

When the totaling facility for user labels is selected with DASD devices and secondary 
space is specified, the total accumulated may be one less than the actual written. 

Data Control Block Open Exit: You can specify in an exit list the address of a routine 
that completes or modifies a DCB and does any additional processing required before the 
data set is completely open. The routine is entered during the opening process after the 
JFCB has been used to supply information for the DCB. The routine can determine data 
set characteristics by examining fields completed from the data set labels. When your 
DCB exit routine receives control, the three, low-order bytes of register 1 will contain 
the address of the DCB currently being processed. 

As with label processing routines, register 14's contents must be preserved and restored 
if any macro instructions are used in the routine. Control is returned to the operating 
system by a RETURN macro instruction; no return code is required. 

This exit is mutually exclusive with the JFCBE exit. If you need both the JFCBE and 
data control block open exits, you must use the JFCBE exit to pass control to your 
routines. 
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QSAM Parallel Input Exit: A request for parallel input processing is indicated by 
including the address of a parallel data access block (PDAB) in the DCB exit list. The 
address must be on a fullword boundary with the first byte of the entry containing X'12' 
or, if it is the last entry, X'92\ For more information on parallel input processing, see 
"Parallel Input Processing (QSAM Only)." 
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JFCBE Exit: JCL-specified setup requirements for the 3800 printer cause a JFCB 
extension (JFCBE) to be created to reflect those specifications. A JFCBE exits if 
BURST, MODIFY, CHARS, FLASH, or any copy group is coded on the DD statement. 
The JFCBE exit can be used to examine or modify those specifications in the JFCBE. 
You can provide a JFCBE exit routine to examine or modify those specifications. The 
address of the routine should be placed in an exit list. The device allocated does not have 
to be a 3800. This exit is taken during open processing and is mutually exclusive with the 
data control block exit. If you need both the JFCBE and data control block exits, you 
must use the JFCBE exit to pass control to your routines. 

When control is passed to your exit routine, the contents of register and 1 will be: 

Register Contents 

If a JFCBE exists, this register will point to an area in unprotected storage into which a copy 
of the JFCBE has been placed. If a JFCBE does not exist, this register will be zero. 

1 The address of the DCB being processed. 

Registers 2-15 will contain the standard user exit contents. 

The area pointed to by register will also contain the 4-byte FCB identification which is 
obtained from the JFCB. The FCB identification is placed in the four bytes following the 
176-byte JFCBE. If the FCB operand was not coded on the DD statement, this FCB 
field will be binary zeros. 

If your copy of the JFCBE is modified during an exit routine, you should indicate this 
fact by turning on bit JFCBEOPN (X*80' in JFCBFLAG) in the JFCBE copy. On 
return to open, this bit indicates whether the system copy is to be updated. The 4-byte 
FCB identification in your area will be used to update the JFCB regardless of the bit 
setting. Checkpoint/restart also interrogates this bit to determine which version of the 
JFCBE will be used at restart time. If this bit is not on, the JFCBE generated by the 
restart JCL will be used. 

End-of-Volume Exit: You can specify in an exit list the address of a routine that is 
entered when end-of-volume is reached in processing of a physical sequential data set. 

When you concatenate data sets with unlike attributes, no EOV exits are taken. 

When the end-of-volume routine is entered, register contains unless user totaling was 
specified. If you specified user totaling in the DCB macro instruction (by coding 
OPTCD=T) or in the DD statement for an output data set, register contains the 
address of the user totaling image area. The routine is entered after a new volume has 
been mounted and all necessary label processing has been completed. If the volume is a 
reel of magnetic tape, the tape is positioned after the tapemark that precedes the 
beginning of the data. 

You can use the end-of-volume (EOV) exit routine to take a checkpoint by issuing the 
CHKPT macro instruction, which is discussed in OS/VS2 Checkpoint /Restart; 
specifications for the CHKPT macro are also included in OS/VS2 MVS Data 
Management Macro Instructions. If a checkpointed job step terminates abnormally, it 
can be restarted from the EOV checkpoint. When the job step is restarted, the volume is 
mounted and positioned as upon entry to the routine. Restart becomes impossible if 
changes are made to the link pack area (LP A) library between the time the checkpoint is 
taken and the time the job step is restarted. When the step is restarted, pointers to 
end-of-volume modules must be the same as when the checkpoint was taken. 

The end-of-volume exit routine returns control in the same manner as the data control 
block exit routine. Register 14's contents must be preserved and restored if any macro 
instructions are used in the routine. Control is returned to the operating system by a 
RETURN macro instruction; no return code is required. 
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Block Count Exit: You can specify in an exit list the address of a routine that will allow 
you to abnormally terminate the task or continue processing when the end-of-volume 
routine finds an unequal block count condition. When you are using standard labeled 
input tapes, the block count in the trailer label is compared by the end-of-volume routine 
with the block count in the DCB. The count in the trailer label reflects the number of 
blocks written when the data set was created. The number of blocks read when the tape 
is used as input is contained in the DCBBLKCT field of the DCB. 

The routine is entered during end-of-volume processing: The trailer label block count is 
passed in register 0. You may gain access to the count field in the DCB by using the 
address passed in register 1 plus the proper displacement, as given in OS/VS2 System 
Programming Library: Debugging Handbook. If the block count in the DCB differs 
from that in the trailer label when no exit routine is provided, the task is abnormally 
terminated. The routine must terminate with a RETURN macro instruction and a return 
code that indicates what action is to be taken by the operating system, as shown in 
Figure 18. As with other exit routines, register 14's contents must be saved and restored 
if any macro instructions are used. 

Return Code System Action 

The task is to be abnormally terminated. 

4 Normal processing is to be resumed. 

Figure 18. System Response to Block Count Exit Return Code 

Defer Nonstandard Input Trailer Label Exit: In an exit list, you can specify a code that 
indicates that you want to defer nonstandard input trailer label processing from 
end-of-data until the data set is closed. The address portion of the entry is not used by 
the operating system. 

An end-of-volume condition exists in several situations. Two examples are: (1) when the 
system reads a filemark or tapemark at the end of a volume of a multivolume data set but 
that volume is not the last, and (2) when the system reads a filemark or tapemark at the 
end of a data set. The first situation is referred to here as an end-of-volume condition, 
and the second as an end-of-data condition, although it, too, can occur at the end of a 
volume.- 

For an end-of-volume (EOV) condition, the EOV routine passes control to your 
nonstandard input trailer label routine, whether or not this exit code is specified. For an 
end-of-data condition when this exit code is specified, the EOV routine does not pass 
control to your nonstandard input trailer label routine. Instead, the close routine passes 
control to your end-of-data routine. 

FCB Image Exit: You can specify in an exit list the address of a forms control buffer 
(FCB) image. This FCB image can be loaded into the forms control buffer of the printer 
control unit. The FCB controls the movement of forms in printers that do not use a 
carriage control tape. 

Multiple exit list entries in the exit list can define FCBs. The open and SETPRT routines 
search the exit list for requested FCBs before searching SYS1.IMAGELIB. 

The first 4 bytes of the FCB image contain the image identifier. To load the FCB, this 
image identifier is specified in the FCB parameter of the DD statement, by the SETPRT 
macro instruction, or by the system operator in response to message IEC 1 27D or 
IEC129D. 

For a 321 1 the image identifier is followed by the FCB image described in OS/VS2 
System Programming Library: Data Management. For a 3800, see IBM 3800 
Printing Subsystem Programmer's Guide. 

You can use an exit list to define an FCB image only when writing to an online printer. 
Figure 19 illustrates one way the exit list can be used to define an FCB image. 
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//ddname DD UNIT=321 1 , FCB=( IMG1 , VERIFY ) 

/* 

Figure 19. Defining an FCB Image for a 321 1 



DCB ABEND Exit: The DCB ABEND exit is provided to give you some options 
regarding the action you want the system to take when a condition arises that may result 
in abnormal termination of your task. This exit can be taken any time an ABEND 
condition arises during the process of opening, closing, or handling an end-of -volume 
condition for a DCB associated with your task. 

When an ABEND condition arises, a write-to-programmer message about the ABEND is 
issued and your DCB ABEND exit is given control, provided there is an active DCB 
ABEND exit routine address in the DCB being processed. If STOW called the 
end-of -volume routines to get secondary space to write an end-of-file mark for a 
partitioned data set, or if the DCB being processed is for an indexed sequential data set, 
the DCB ABEND exit routine will not be given control if an ABEND condition occurs. 
The contents of the registers when your exit routine is entered are the same as for other 
DCB exit list routines except that the three, low-order bytes of register 1 contain the 
address of the parameter list described in Figure 20. Your ABEND exit routine can 
choose one of four options: 

• to immediately terminate your task, 

• to delay the ABEND until all of the DCBs in the same OPEN or CLOSE macro 
instruction are opened or closed, 

• to ignore the ABEND condition and continue processing without making reference to 
the DCB on which the ABEND condition was encountered, or 

• to try to recover from the error. 
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0-3 
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OK to Recover 
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OK to Ignore 
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OK to Delay 
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Reserved for Future Use 



Displacement 



Fullword Boundary 








System Completion Code* 


Return Code 


Option Mask 


4 


DCB Address 


8 


Open/Close/End-of-Volume Work Area Address 


12 


00 


Recovery Work Area Address 



*ln the first 12 bits. 
Figure 20. Parameter List Passed to DCB ABEND Exit Routine 



Not all of these options are available for each ABEND condition. Your DCB ABEND 
exit routine must determine which option is available by examining the contents of the 
option mask byte (byte 3) of the parameter list. The address of the parameter list is 
passed in register 1. Figure 20 shows the contents of the parameter list and the possible 
settings of the option mask when your routine receives control. All information in the 
parameter list is in binary. 

When your DCB ABEND exit routine returns control to the system control program 
(this can be done using the RETURN macro instruction), the option mask byte should 
contain the setting that specifies the action you want to take. These actions and the 
corresponding settings of the option mask byte are: 

Bit Setting Action 

abnormally terminate the task immediately 

4 ignore the ABEND condition 

8 delay the ABEND until the other DCBs being processed concurrently are opened or closed 

12 make an attempt to recover 

You must inspect bits 4, 5, and 6 of the option mask byte (byte 3 of the parameter list) 
to determine which options are available. If a bit is set to 1 , the corresponding option is 
available. Indicate your choice by inserting the appropriate value in byte 3 of the 
parameter list, overlaying the bits you inspected. If you use a value that specifies an 
option that is not available, the ABEND is issued immediately. 
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If the contents of the option mask are 0, you must request an immediate ABEND by 
leaving the value of in the option mask unchanged. 

If bit 5 of the option mask is set to 1, you can ignore the ABEND by placing a decimal 
value of 4 in byte 3 of the parameter list. Processing on the current DCB stops. If you 
subsequently attempt to use this DCB, the results are unpredictable. If you ignore an 
error in end-of-volume, the data set will be closed before control is returned to your 
program at the point which caused the end-of-volume condition (unless the 
end-of-volume routines were called by the close routines). If the end-of-volume routines 
were called by the close routines, an ABEND macro will be issued even though the 
ignore option was selected. 

If bit 6 of the option mask is set to 1, you can delay the ABEND by placing a decimal 
value of 8 in byte 3 of the parameter list. All other DCBs waiting for open or close 
processing will be processed before the ABEND is issued. For end-of-volume, however, 
you can't delay the ABEND because the end-of-volume routine never has more than one 
DCB to process. 

If bit 4 of the option mask is set to 1 , you can attempt to recover. Place a decimal value 
of 12 in byte 3 of the parameter list and provide information for the recovery attempt. 
Figure 21 lists the ABEND conditions for which recovery can be attempted. For 
ABEND conditions which can be ignored or delayed, see OS/VS Message Library: 
VS2 System Messages. 



Description of Error 

DSCB was not found on volume specified. 

Block count in DCB does not agree with block count in trailer label. 

Data set was opened for input and no volume serial number was specified. 

I/O error occurred during reading of tape label. 

Invalid tape label was read. 

I/O error occurred during writing of tape label. 

I/O error occurred during writing of tapemark following header labels. 

A data set on magnetic tape was opened for INOUT, but the volume 
contained a data set whose expiration date had not been reached and the 
operator denied permission. 

I/O error occurred during reading of trailer label I to update block count in 
DCB. 

Data set name on header label does not match data set name on DD 
statement. 

Figure 21. Conditions for which Recovery Can Be Attempted 

Recovery Requirements: For the recovery attempt, you should supply a recovery work 
area (see Figure 22) with a new volume serial number for each volume associated with 
an error. If no new volumes are supplied, recovery will be attempted with the existing 
volumes, but the likelihood of successful recovery is greatly reduced. 

If you request recovery for system completion code 213, return code 04, you must 
indicate in your job control language (JCL) that the volumes are nonsharable by 
specifying unit affinity, deferred mounting, or more volumes than units for the data set. 

If you request recovery for system completion code 237, return code 04, you don't need 
to supply new volumes or a work area. The condition that caused the ABEND is the 
disagreement between the block count in the DCB and that in the trailer label. This 
disagreement is ignored to permit recovery. 
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Figure 22. Recovery Work Area 



If you request recovery for system completion code 717, return code 10, you don't need 
to supply new volumes or a work area. The ABEND is caused by an I/O error during 
updating of the DCB block count. To permit recovery, the block count is not updated. 
Consequently, an abnormal termination with system completion code 237, return code 
04, may result when you try to read from the tape after recovery. You may attempt 
recovery from the ABEND with system completion code 237, return code 04, as 
explained in the preceding paragraph. 

System completion codes and their associated return codes are described in OS/VS 
Message Library: VS2 System Codes. 

The work area that you supply for the recovery attempt must begin on a halfword 
boundary and can contain the information described in Figure 22. Place a pointer to the 
work area in the last 3 bytes of the parameter list pointed to by register 1 and described 
in Figure 20. 

If you acquire the storage for the work area by using the GETMAIN macro instruction, 
you can request that it be freed by a FREEMAIN macro instruction after all information 
has been extracted from it. Set the high-order bit of the option byte in the work area to 1 
and place the number of the subpool from which the work area was requested in byte 3 
of the recovery work area. 

Only one recovery attempt per data set is allowed during open, close, or end-of-volume 
processing. If a recovery attempt is unsuccessful, you may not request another recovery. 
The second time through the exit routine you may request only one of the other options 
(if allowed): issue the ABEND immediately, ignore the ABEND, or delay the ABEND. 
If at any time you select an option that is not allowed, the ABEND is issued immediately. 
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Note that if recovery is successful, you still receive an ABEND message on your listing. 
This message refers to the ABEND that would have been issued if the recovery had not 
been successful. 



Modifying the Data Control Block 



You can complete or modify the DCB during execution of your program. You can also 
determine data set characteristics from information supplied by the data set labels. 
Changes or additions can be made before opening of the data set, after closing it, during 
the DCB exit routine, or while the data set is open. Naturally, any information must be 
supplied before it is needed. 

Because each DCB does not have a symbolic name for each field, a DCBD macro 
instruction must be used to supply the symbolic names. By loading a base register with 
the address of the DCB to be processed, you can refer to any field symbolically. 

The DCBD macro instruction generates a dummy control section (DSECT) named 
IHADCB. The name of each field consists of DCB followed by the first five letters of 
the keyword operand that represents the field in the DCB macro instruction. For 
example, the field reserved for blocksize is referred to as DCBBLKSI. For the names of 
other fields, including names of bits, see OS/ VS2 MVS Data Management Macro 
Instructions. 

The attributes of each DCB field are defined in the dummy control section. Because each 
field in the DCB is not necessarily aligned on a fullword boundary, care must be taken 
when storing or moving data into the field. The length attribute and the alignment of 
each field can be determined from an assembly listing of the DCBD macro instruction. 

The DCBD macro instruction can be coded once to describe all DCBs even though their 
fields differ because of differences in data set organization and access technique. It must 
not be coded more than once for a single assembly. If it is coded before the end of a 
control section, it must be followed by a CSECT or DSECT statement to resume the 
original control section. 

Changing an Address in the Data Control Block: Figure 23 illustrates how you can modify 
a field in the data control block. The DCBD macro instruction defines the symbolic name 
of each field. 



OPEN ( TEXTDCB , INOUT ) 

( TEXTDCB , REREAD ) , TYPE=T 

10, TEXTDCB 

IHADCB, 10 

DCBS YNAD+ 1(3), =AL3 ( OUTERROR ) 

OUTPUT 

14, 12,SYNADSA+12 

14,12, SYNADSA+ 1 2 

DSORG=PS,MACRF=(R,W),DDNAME=TEXTTAPE, C 
EODAD=EOFEXIT , SYNAD=INERROR 
DSORG=PS 

Figure 23. Modifying a Field in the Data Control Block 

The data set defined by the data control block TEXTDCB is opened for use as both an 
input and an output data set. When its use as an input data set is completed, the EODAD 
routine closes the data set temporarily to reposition the volume for output. The EODAD 
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routine then uses the dummy control section IHADCB to change the error exit address 
(SYNAD) from INERROR to OUTERROR. 

The EODAD routine loads the address TEXTDCB into register 10, which it uses as a 
base register for IHADCB. It then moves the address OUTERROR into the 
DCBSYNAD field of the DCB. This field is a fullword, but contains information that 
must not be disturbed in the high-order byte. For this reason, care must be taken to 
change only the 3 low-order bytes of the field. 

All unused address fields in the DCB, except DCBEXLST, are set to 1 during the DCB 
macro expansion. Many system routines interpret a value of 1 in an address field to mean 
"no address specified." If you modify an address field and then want to reset it to "no 
address specified," you should set it to a value of 1. 



Sharing a Data Set 



There are two conditions under which a data set on a direct-access device can be shared 
by two or more tasks: 

• Two or more DCBs are opened and used concurrently by the tasks to refer to the 
same, shared data set (multiple DCBs). 

• Only one DCB is opened and used concurrently by multiple tasks in a single job step 
(a single, shared DCB). 

Job control language (JCL) statements and macro instructions are provided in the 
operating system to help you to ensure the integrity of the data sets you wish to share 
among the tasks that process them. Figures 24 and 25 show which JCL and macro 
instructions you should use, depending on the access method your task is using and mode 
of access (input, output, or update). 

Figure 24 describes the macro instructions, JCL, and processing procedures you should 
use if more than one DCB has been opened to the shared data set. The DCBs can be 
used by tasks in the same or different job steps. 
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Access Method 
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Input 
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DISP = SHR 


DISP = SHR 


DISP » SHR 


DISP = SHR 


Output 
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DISP - SHR and 
ENQ on Data Set 


Update 


DISP = SHRand 
ENQon Block 


DISP = SHRand 
Guarantee Discrete 
'Blocks 


DISP = SHR and 
ENQ on Block 


DISP - SHR and 
ENQ on Data Set 
and Guarantee 
Discrete Blocks 


DISP - SHR and 
ENQ on Data Set 
and Guarantee 
Discrete Blocks > 



D1SP-SHR: 

Each job step sharing an existing data set must code SHR as the subparameter of the DISP parameter on (he DD statement for 
the shared data set to allow the steps to execute concurrently. For additional information about ensuring data set integrity, sec 
OS/VS2 JCL. If the tasks are in the same job step, DISP=SHR is not required. 

No Facility: 

There are no facilities in the operating system for sharing a data set under these conditions. 

ENQ on Data Set: 

In addition to coding DISP=SHR on the DD statement for the data set that is to.be shared, each task must issue ENQ and 
DEQ macro instructions naming the data set as resource for which exclusive control is required. The ENQ must be issued 
before the GET (READ); the DEQ macro should be issued after the PUTX or CHECK macro that concludes the operation. 
See 0S/VS2 Supervisor Services and Macro Instructions for additional information on the use of ENQ and DEQ macro 
instructions. 

Guarantee Discrete Blocks: 

When you are using the access methods that provide blocking and unblocking of records (QSAM, QISAM, and BISAM), il is 
necessary that every task updating the data set ensure that it is not updating a block that contains a record being updated by 
any other task. There are no facilities in the operating system for ensuring that discrete blocks are being processed by different 
tasks. 

ENQ on Block: 

If you are updating a shared data set (specified by coding DISP-SHR on the DD statement) using BSAM or BPAM, your task 
and all other tasks must serialize processing of each block of records by issuing an ENQ macro instruction before the READ 
macro and a DEQ macro after the CHECK macro that follows the WRITE macro you issued to update the record, If you are 
using BDAM, the same procedure may be used; however, BDAM provides for enqueuing on a block of records using the 
READ exclusive option, which is requested by coding MACRF-X in the DCB and an X in the type operand of the READ and 
WRITE macro instructions. See "Exclusive Control for Updating" in the section "Processing a Direct Data Set" of Part 2 for 
an example of the use of the BDAM macros. 

Figure 24. JCL, Macro Instructions, and Procedures Required to Share a Data Set Using Multiple DCBs 
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Figure 25 describes the macros you can use to serialize processing of a shared data set 
when a single DCB is being shared by several tasks in a job step. The DISP=SHR 
specification on the DD statement is not required. 

Data sets can also be shared both ways at the same time: more than one DCB can be 
opened for a shared data set, while more than one task can be sharing one of the DCBs. 
Under this condition, the serialization techniques specified for indexed sequential and 
direct data sets in the Figure 24 satisfy the requirement. For sequential and partitioned 
data sets, the techniques specified in Figure 24 and Figure 25 must be used. 



A SINGLE SHARED DCB 



Access Mode 


Access Method 


BSAM, BPAM, 
BDAM Create 


QSAM 


BDAM 


QISAM 


BISAM 


Input 


ENQ 


ENQ 


No Action 
Required 


ENQ 


ENQ 


Output 


ENQ 
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ENQ: 

When a data set is being shared by two or more tasks in the same job step (all of which must be using the same DCB), each 
task processing the data set must issue an ENQ macro instruction on a predefined resource name before issuing the macro or 
macros that begin the input/output operation. Each task must also release exclusive control by issuing the DEQ macro 
instruction at the next sequential instruction following the input/output macro. If, however, you are processing an indexed 
sequential data set sequentially using the SETL and ESETL macros, you must issue the ENQ macro before the SETL macro 
and the DEQ macro after the ESETL macro. Note also that if two tasks are writing different members of a partitioned data 
set, each task should issue the ENQ macro instruction before the FIND macro and issue the DEQ macro after the STOW 
macro that completes processing of the member. Additional reference information on the ENQ and DEQ macros is presented 
in OS/VS2 Supervisor Services and Macro Instructions. For an example of the use of ENQ and DEQ macro instructions with 
BISAM, see Figure 59. 

No Action Required: 

Sharing a Direct Data Set: BDAM supports multiple task users of a single DCB when working with existing data sets. When 
operating in load mode, however, only one task may use the DCB at a time. The following restrictions and comments apply 
when operating in a multitasking mode with existing data sets: 

• Subpool must be shared. 

• The user should insure that a WAIT or CHECK macro has been issued for all outstanding BDAM requests before the task 
issuing the READ or WRITE macro terminates. In case of abnormal termination this can be done through a STAE/STAI 
brESTAEexit. 

• FREEDBUF and/or RELEX macros should be issued to free any resources that could still be held by the terminating task. 
This can be done during or after task termination. 

ENQ on Block: 

When updating a shared BDAM data set, every task must use the BDAM exclusive control option, which is requested by 
coding MACRF-X in the DCB macro and an X in the type operand of the READ and WRITE macro instructions. See 
"Exclusive Control for Updating" in this book for an example of the use of BDAM macros. Note that all tasks sharing a data 
set must share subpool (see the ATTACH macro description in OS/VS2 Supervisor Services and Macro Instructions). 

Key Sequence: 

Tasks sharing a QISAM load-mode DCB must ensure that the records to be written are presented in ascending key sequence; 
otherwise, a sequence check will result in (1) control being passed to the SYNAD routine identified by the DCB, or (2) if there 
is no SYNAD routine, termination of the task. 

Figure 25. Macro Instructions and Procedures Required to Share a Data Set Using a Single DCB 
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More information on opening and closing data sets by more than one task is contained in 
Part 2, "Opening and Closing a Data Set." 

Shared Direct-Access Storage Devices: At some installations, a direct-access storage 
device is shared by two or more independent computing systems. Tasks executed on 
these systems can share data sets stored on the device. For details, refer to OS/VS2 
System Programming Library: Supervisor. 



Part I: Introduction to Data Management 57 



PART 2: DATA MANAGEMENT PROCESSING 
PROCEDURES 

Data-Processing Techniques 

The operating system allows you to concentrate most of your efforts on processing the 
records read or written by the data management routines. To get the records read and 
written, your main responsibilities are to describe the data set to be processed, the 
buffering techniques to be used, and the access method. An access method has been 
defined as the combination of data set organization and the technique used to gain access 
to the data. Data access techniques are discussed here in two categories — queued and 
basic. 

Queued Access Technique 

The queued access technique provides GET and PUT macro instructions for transmitting 
data within virtual storage. These macro instructions cause automatic blocking and 
deblocking of the records stored and retrieved. Anticipatory (look-ahead) buffering and 
synchronization (overlap) of input and output operations with central processing unit 
(CPU) processing are automatic features of the queued access technique. 

Because the operating system controls buffer processing, you can use as many 
input/output (I/O) buffers as needed without reissuing GET or PUT macro instructions 
to fill or empty buffers. Usually, more than one input block is in storage at any given 
time, so I/O operations do not delay record processing. 

Because the operating system synchronizes input/output with processing, you need not 
test for completion, errors, or exceptional conditions. After a GET or PUT macro 
instruction is issued, control is not returned to your program until an input area is filled 
or an output area is available. Exits to error analysis (SYNAD) and end-of-volume or 
end-of-data (EODAD) routines are automatically taken when necessary. 



GET — Retrieve a Record 



The GET macro instruction obtains a record from an input data set. It operates in a 
logical sequential and device-independent manner. As required, the GET macro 
instruction schedules the filling of input buffers, deblocks records, and directs input error 
recovery procedures. For sequential data sets, it also merges record segments into logical 
records. After all records have been processed and the GET macro instruction detects an 
end-of-data indication, the system automatically checks labels on sequential data sets and 
passes control to your end-of-data (EODAD) routine. If an end-of-volume condition is 
detected for a sequential data set, the system provides automatic volume switching if the 
data set extends across several volumes or if concatenated data sets are being processed. 
If you specify OPTCD=Q in the DCB, GET causes input data to be translated from 
ASCII to EBCDIC. 



PUT— Write a Record 



The PUT macro instruction places a record into an output data set. Like the GET macro 
instruction, it operates in a logical sequential and device-independent manner. As 
required, the PUT macro instruction schedules the emptying of output buffers, blocks 
records, and handles output error correction procedures. For sequential data sets, it also 
initiates automatic volume switching and label creation, and also segments records for 
spanning. If you specify OPTCD=Q in the DCB, PUT causes output to be translated 
from EBCDIC to ASCII. 
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If the PUT macro instruction is directed to a card punch or printer, the system 
automatically adjusts the number of records or record segments per block of format-F or 
format- V blocks to 1. Thus, you can specify a record length (LRECL) and blocksize 
(BLKSIZE) to provide an optimum blocksize if the records are temporarily placed on 
magnetic tape or a direct-access volume. 

For spanned variable-length records, the blocksize must be equivalent to the length of 
one card or one print line. Record size may be greater than blocksize in this case. 



PUTX — Write an Updated Record 



The PUTX macro instruction is used to update a data set or to create an output data set 
using records from an input data set as a base. PUTX updates, replaces, or inserts 
records from existing data sets but does not create records. 

When you use the PUTX macro instruction to update, each record is returned to the data 
set referred to by a previous locate mode GET macro instruction. The buffer containing 
the updated record is flagged and written back to the same location on the direct-access 
storage device from which it was read. The block is not written until a GET macro 
instruction is issued for the next buffer, except when a spanned record is to be updated. 
In that case, the block is written with the next GET macro instruction. 

When the PUTX macro instruction is used to create an output data set, you can add new 
records by using the PUT macro instruction. As required, the PUTX macro instruction 
blocks records, schedules the writing of output buffers, and handles output error 
correction procedures. 



Parallel Input Processing (QSAM Only) 



QSAM parallel input processing may be used to process two or more input data sets 
concurrently, such as sorting or merging several data sets at the same time. This 
eliminates the need for issuing a separate GET macro instruction to each DCB 
processed. The get routine for parallel input processing selects a DCB with a ready 
record and then transfers control to the normal get routine. If there is no DCB with a 
ready record, a multiple WAIT macro instruction is issued. 

Parallel input processing provides a logical input record from a queue of data sets with 
equal priority. The function supports QSAM with input processing, simple buffering, 
locate or move mode, and fixed, variable, or undefined length records. Spanned records, 
track-overflow records, dummy data sets, and SYSIN data sets are not supported. 

Parallel input processing can be interrupted at any time to retrieve records from a 
specific data set, or to issue control instructions to a specific data set. When the retrieval 
process has been completed, parallel input processing may be resumed. 

Data sets can be added to or deleted from the data set queue at any time. It is important 
to note, however, that as each data set reaches an end-of-data condition, the data set 
must be removed from the queue with the CLOSE macro instruction before a subsequent 
GET macro instruction is issued for the queue; otherwise, the task may be terminated 
abnormally. 

A request for parallel input processing is indicated by including the address of a parallel 
data access block (PDAB) in the DCB exit list. For additional information on the DCB 
exit list, see "Exit List (EXLST)." 

With the use of the PDAB macro instruction, you can create and format a work area that 
identifies the maximum number of DCBs that can be processed at any one time. If you 
exceed the maximum number of entries indicated in the PDAB macro when adding a 
DCB to the queue with the OPEN macro, the data set will not be available for parallel 
input processing; however, it may be available for sequential processing. 
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When issuing a parallel GET macro, register 1 must always point to a PDAB. You may 
load the register or let the GET macro do it for you. When control is returned to you, 
register 1 contains the address of a logical record from one of the data sets in the queue; 
registers 2-13 contain their original contents at the time the GET macro was issued; 
registers 14, 15, and are changed. You can locate the data set from which the record 
was retrieved through the PDAB. A fullword address in the PDAB (PDADCBEP) points 
to the address of the DCB. It should be noted that this pointer may be invalid from the 
time a CLOSE macro is issued to the issuing of the next parallel GET macro. 

In Figure 26, not more than three data sets (MAXDCB=3 in the PDAB operand) will be 
open for parallel processing at any given time. Assuming that data definition statements 
and data sets are supplied, DATASET1, DATASET2, and DATASET3 will be opened 
for parallel input processing as specified in the input processing OPEN macro instruction. 
Other attributes of each data set are QSAM (MACRF=G), simple buffering by default, 
locate or move mode (MACRF=L or M), fixed length records (RECFM=F), and exit 
list entry for a PDAB (X'92'). Note that both locate and move modes may be used in the 
same data set queue. The mapping macros, DCBD and PDABD, are used to reference 
the DCBs and the PDAB respectively. 
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Figure 26. Parallel Processing of Three Data Sets 



Part 2: Data Management Processing Procedures 61 



Page of GC26-3875-0 
Revised June 29, 1979 
By TNL GN26-0944 



Following the OPEN macro instruction, tests are made to determine whether the DCBs 
were opened for parallel processing. If not, the sequential processing routine is given 
control. 

When one or more data sets are opened for parallel processing, the get routine retrieves a 
record, saves the pointer in register 10, processes the record, and writes it to 
DATASET4. This process continues until an end-of-data condition is detected on one of 
the input data sets; the end-of-data routine locates the completed input data set and 
removes it from the queue with the CLOSE macro instruction. A test is then made to 
determine whether any data sets remain on the queue. Processing continues in this 
manner until the queue is empty. 



Basic Access Technique 



The basic access technique provides the READ and WRITE macro instructions for 
transmitting data between virtual and auxiliary storage. This technique is used when the 
operating system cannot predict the sequence in which the records are to be processed or 
when you do not want some or all of the automatic functions performed by the queued 
access technique. Although the system does not provide anticipatory buffering or 
synchronized scheduling, macro instructions are provided to help you program these 
operations. 

The READ and WRITE macro instructions process blocks, not records. Thus, blocking 
and deblocking of records is your responsibility. Buffers, allocated by either you or the 
operating system, are filled or emptied individually each time a READ or WRITE macro 
instruction is issued. Moreover, the READ and WRITE macro instructions only initiate 
input/output operations. To ensure that the operation is completed successfully, you 
must issue a CHECK macro instruction to test the data event control block (DECB) or 
issue a WATT macro instruction and then check the DECB yourself. (The only exception 
to this is when the SYNAD or EODAD routine is entered, neither a WATT or CHECK 
macro instruction should be issued to previously outstanding READ or WRITE 
requests.) The number of READ or WRITE macro instructions issued before a CHECK 
macro instruction is used should not exceed the specified number of channel programs 
(NCP). 

Grouping Related Control Blocks in a Paging Environment: In an OS/VS system, related 
control blocks (the DCB and DECB) and data areas (buffers and key areas) should be 
coded so they assemble in the same area of your program. This will reduce the number of 
paging operations required to read from and write to your data set. 

Using Overlapped I/O with BSAM: When using BSAM with overlapped I/O (multiple 
I/O requests outstanding at one time), more than one DECB must be used. A different 
DECB should be specified for each channel program. For example, if you specify 
NCP=3 in your DCB for the data set and you are reading records from the data set, you 
should code the following macros in your program: 

READ DECBl,... 
READ DECB2,... 
READ DECB3,... 
CHECK DECBl 
CHECK DECB2 
CHECK DECB3 

Using Overlapped I/O with BDAM: When using BDAM with overlapped I/O requests, a 
different DECB must be used for each request that will be outstanding when another 
request is issued. In addition, consecutive requests for the same record (such as a write 
followed by a read) must not be overlapped. In this case, the completion of the write 
request must be tested prior to issuance of the read request. 
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READ— Read a Block 



The READ macro instruction retrieves a data block from an input data set and places it 
in a designated area of virtual storage. To allow overlap of the input operation with 
processing, the system returns control to your program before the read operation is 
completed. The DECB created for the read operation must be tested for successful 
completion before the record is processed or the DECB is reused. 

If an indexed sequential data set is being read, the block is brought into virtual storage 
and the address of the record is returned to you in the DECB. 

When you use the READ macro instruction for BSAM to read a direct data set with 
spanned records and keys and you specify BFTEK=R in your DCB, the data 
management routines displace record segments after the first in a record by key length. 
Thus, you can expect the block descriptor word and the segment descriptor word at the 
same locations in your buffer or buffers, regardless of whether you read the first segment 
of a record, which is preceded in the buffer by its key, or a subsequent segment, which 
does not have a key. This procedure is called offset reading. 

You can specify variations of the READ macro instruction according to the organization 
of the data set being processed and the type of processing to be done by the system as 
follows: 

Sequential . . 

SF - Read the data set sequentially. 

SB - Read the data set backward (magnetic tape, format-F and format-U 

only). When RECFM = FBS, data sets with the last block truncated 

cannot be read backward. 

Indexed Sequential 

K - Read the data set. 

K.U - Read for update. The system maintains the device address of the 

record; thus, when a WRITE macro instruction returns the record, no 

index search is required. 
Direct 

D - Use the direct access method. 

I - Locate the block using a block identification. 

K - Locate the block using a key. 

F - Provide device position feedback. 

X - Maintain exclusive control of the block. 

R - Provide next address feedback. 

U - Next address can be a capacity record or logical record, whichever 

occurred first. 



WRITE— Write a Block 



The WRITE macro instruction places a data block in an output data set from a 
designated area of virtual storage. The WRITE macro instruction can also be used to 
return an updated record to a data set. To allow overlap of output operations with 
processing, the system returns control to your program before the write operation is 
completed. The DECB created for the write operation must be tested for successful 
completion before the DECB can be reused. For ASCII tape data sets, do not issue more 
than one WRITE on the same record, because the WRITE macro instruction causes the 
data in the record area to be translated from EBCDIC to ASCII. 
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As with the READ macro instruction, you can specify variations of the WRITE macro 
instruction according to the organization of the data set and the type of processing to be 
done by the system as follows: 

Sequential 

SF - Write the data set sequentially. 

SFR - Write the data set sequentially with next-address feedback. 

Indexed Sequential 

K. - Write a block containing an updated record, or replace a record with 
a fixed, unblocked record having the same key. The record to be 
replaced need not have been read into virtual storage. 

KN - Write a new record or change the length of a variable-length record. 

Direct 

SD - Write a dummy fixed-length record. 

SZ - Write a capacity record (RO). The system supplies the data, 
writes the capacity record, and advances to the next track. 

D - Use the direct access method. 

I - Search argument identifies a block. 

K - Search argument is a key. 

A - Add a new block. 

F - Provide record location data (feedback). 

X - Release exclusive control. 



CHECK — Test Completion of Read or Write Operation 



When processing a data set, you can test for completion of a READ or WRITE request 
by issuing a CHECK macro instruction. The system tests for errors and exceptional 
conditions in the data event control block (DECB). Successive CHECK macro 
instructions issued for the same data set must be issued in the same order as the 
associated READ and WRITE macro instructions. 

The check routine passes control to the appropriate exit routines specified in the DCB 
for error analysis (SYNAD) or, for sequential data sets, end-of-data (EODAD). It also 
automatically initiates end-of-volume procedures (volume switching or extending output 
data sets). 

If you specify OPTCD=Q in the DCB, CHECK causes input data to be translated from 
ASCII to EBCDIC. 



WAIT — Wait for Completion of a Read or Write Operation 



When processing a data set, you can test for completion of any READ or WRITE 
request by issuing a WAIT macro instruction. The input/output operation is 
synchronized with processing, but the DECB is not checked for errors or exceptional 
conditions, nor are end-of-volume procedures initiated. Your program must perform 
these operations. 

For BDAM and BISAM, a WAIT macro must be issued for each READ or WRITE 
macro if MACRF=C is not coded in the associated DCB. When MACRF=C is coded, 
and at all times for BSAM and BPAM, a CHECK macro must be issued for each READ 
or WRITE macro. Since the CHECK macro incorporates the function of the WAIT 
macro, a WAIT is normally redundant for those access methods. The ECBLIST form of 
the WAIT macro may be useful, though, in selecting which of a number of outstanding 
events should be checked first. 

The WAIT macro instruction can be used to await completion of multiple read and write 
operations. Each operation must then be checked or tested separately. 

Example: You have opened an input DCB for BSAM with NCP=2, and an output DCB 
for BISAM with NCP=1 and without specifying MACRF=C. You have issued two 
BSAM READ macros and one BISAM WRITE macro. You now issue the WAIT macro 
with ECBLIST pointing to the BISAM DECB and the first BSAM DECB. (Since BSAM 
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requests are serialized, the first request must execute before the second one.) When you 
regain control, you will inspect the DECBs to see which has completed (second bit on). 
If it was BISAM, you will issue another WRITE macro. If it was BSAM, you will issue a 
CHECK macro and then another READ macro. 



Data Event Control Block (DECB) 



Error Handling 



A data event control block is a 16- to 32-byte area reserved by each READ or WRITE 
macro instruction. It contains control information and pointers to standard status 
indicators. It is described in detail in Appendix A of OS/VS2 MVS Data Management 
Macro Instructions. 

The DECB is examined by the check routine when the I/O operation is completed to 
determine if an uncorrectable error or exceptional condition exists. If it does, control is 
passed to your SYNAD routine. If you have no SYNAD routine, the task is abnormally 
terminated. 



The basic and queued access techniques both provide special macro instructions for 
analyzing input/output errors. These macro instructions can be used in SYNAD routines 
and in error analysis routines that are entered directly when you use the basic access 
technique with indexed sequential data sets. 



SYNADAF— Perform SYNAD Analysis Function 



The SYNADAF macro instruction analyzes the status, sense, and exceptional condition 
code data that is available to your error analysis routine. It produces an error message 
that your routine can write into any appropriate data set. The message is in the form of 
an unblocked variable-length record, but you can write it as a fixed-length record by 
omitting the block length and record length fields that precede the message text. 

The text of the message is 120 characters long, and begins with a field of 36 or 42 
blanks; you can use the blank field to add your own remarks to the message. Following is 
a typical message with the blank field omitted: 

, TESTJOBb , STEP2&56 , 283 , TA , MASTERBfr , READS , DATA CHECK&bbbb , 
0000015, BSAM 

This message indicates that a data check occurred during reading of the fifteenth block of 
a data set. The data set was identified by a DD statement named MASTER, and was on 
a magnetic-tape volume on unit 283. The name of the job was TESTJOB; the name of 
the job step was STEP2. 

If the error analysis routine is entered because of an input error, the first 6 bytes of the 
message (bytes 8-13) contain binary information. If no data was transmitted or if the 
access method is QISAM, the first 6 bytes are blanks or binary zeros. If the error did not 
prevent data transmission, the first 6 bytes contain the address of the input buffer and 
the number of bytes read. You can use this information to process records from the 
block; for example, you might print each record after printing the error message. Before 
printing the message, however, you should replace this binary information with EBCDIC 
characters. 

The SYNADAF macro instruction provides its own save area and makes this area 
available to your error analysis routine. When used at the entry point of a SYNAD 
routine, it fulfills the routine's responsibility for providing a save area. 
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SYNADRLS — Release SYNADAF Message and Save Areas 



The SYNADRLS macro instruction releases the message and save areas provided by the 
SYNADAF macro instruction. You must issue this macro instruction before returning 
from the error analysis routine. 



ATLAS — Perform Alternate Track Location Assignment 



The ATLAS macro instruction enables your program to recover from permanent 
input/output errors when processing a data set in direct-access storage. After a data 
check, or in certain missing-address-marker conditions, you can issue ATLAS to assign 
an alternate track to replace the error track or transfer data from the error track to the 
alternate track. 

The use of this macro requires a knowledge of channel programming. A detailed 
description of the macro instruction and its use is included in OS/ VS2 System 
Programming Library: Data Management. 

If you do not use the ATLAS macro instruction, you can use the IEHATLAS utility 
program to perform the same function. The principal difference between the macro 
instruction and the utility program is that the latter provides error recovery only after 
your own program has been completed. For a detailed description of IEHATLAS, refer 
to OS/VS Utilities. 



Selecting an Access Method 



Access methods are identified primarily by the data set organization to which they apply. 
For instance, BDAM is the basic access method for direct organization. Nevertheless, 
there are times when an access method identified with one organization can be used to 
process a data set usually thought of as organized in a different manner. Thus, a data set 
created by the basic access method for sequential organization (BSAM) may be 
processed by the basic direct access method (BDAM). If the queued access technique is 
used to process a sequential data set, the access method is referred to as the queued 
sequential access method (QSAM). 

Basic access methods are used for all data organizations, while queued access methods 
apply only to sequential and indexed sequential data sets as shown in Figure 27. 

Data Set 

Organization Access Technique 

Basic Queued 

Sequential BSAM QSAM 

Partitioned BPAM 

Indexed Sequential BISAM QISAM 

Direct BDAM 

Figure 27. Data Management Access Methods 

It is possible to control an I/O device directly while processing a data set with any data 
organization without using a specific access method. The execute channel program 
(EXCP) macro instruction uses the system programs that provide for scheduling and 
queuing I/O requests, efficient use of channels and devices, data protection, interruption 
procedures, error recognition and retry. Complete details about the EXCP macro are in 
OS/VS2 System Programming Library: Data Management. 
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Temporary data sets can be handled by a facility called virtual I/O (VIO). Data sets for 
which VIO is specified are located in external page storage. However, to the access 
methods (BDAM, BPAM, BSAM, QSAM, and EXCP), the data sets appear to reside on 
a real direct-access storage device. VIO provides these advantages: 

• Elimination of some of the usual I/O device allocation and data management 
overhead for temporary data sets. 

• Generally more efficient use of direct-access storage space. 

To use VIO, you must specify VIO=YES in the UNITNAME macro during system 
generation, and you must specify a unit name (defined in the UNITNAME macro) on 
the DD statement for your data set. For additional information on VIO, see OS/VS2 
System Programming Library: Initialization and Tuning Guide. For information on 
the UNITNAME macro, see OS/VS2 System Programming Library: System 
Generation Reference. For information on changes to the DD statement, see 
OS/VS2 JCL. 



Opening and Closing a Data Set 



Although your program has been assembled, the various data management routines 
required for I/O operations are not a part of the object code. In other words, your 
program is not completely assembled until the DCBs are initialized for execution. You 
accomplish initialization by issuing the OPEN macro instruction. After all DCBs have 
been completed, the system ensures that all required access method routines are loaded 
and ready for use and that all channel command word lists and buffer areas are ready. 

Access method routines are selected and loaded according to data control fields that 
indicate: 

• Data organization 

• Buffering technique 

• Access technique 

• I/O unit characteristics 

This information is used by the system to allocate virtual-storage space and load the 
appropriate routines. These routines, the channel command word (CCW) lists, and 
buffer areas created automatically by the system remain in virtual storage until the close 
routine signals that they are no longer needed by the DCB that was using them. 

When I/O operations for a data set are completed, you should issue a CLOSE macro 
instruction to return the DCB to its original status, handle volume disposition, create data 
set labels, complete writing of queued output buffers, and free virtual and auxiliary 
storage. 

Managing Buffer Pools when Closing Data Sets: After closing the data set, you should 
issue a FREEPOOL macro instruction to release the virtual storage used for the buffer 
pool. If you plan to process other data sets, use FREEPOOL to regain the buffer pool 
storage space. If you expect to reopen a data set using the same DCB, use FREEPOOL 
unless the buffer pool created the first time the data set was opened will meet your needs 
when you reopen the data set. FREEPOOL is discussed in more detail in the section 
"Buffer Pool Construction." 

After the data set has been closed, the DCB can be used for another data set. If you do 
not close the data set before a task terminates, the operating system closes it 
automatically. If the DCB is not available to the system at that time, the operating 
system abnormally terminates the task, and data results can be unpredictable. Note, 
however, that the operating system cannot automatically close any open data sets after 
the normal termination of a program that was brought into virtual storage by the loader. 
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Therefore, loaded programs must include CLOSE macro instructions for all open data 
sets. 

Simultaneous Opening and Closing of Multiple Data Sets: An OPEN or CLOSE macro 
instruction can be used to initiate or terminate processing of more than one data set. 
Simultaneous opening or closing is faster than issuing separate macro instructions; 
however, additional storage space is required for each data set specified. The coding 
examples in Figures 28 and 29 show the macro expansions for simultaneous open and 
close operations. 

Opening and Closing Data Sets Shared by More Than One Task: When more than one 
task is sharing a data set, the following restrictions must be recognized. Failure to adhere 
to these restrictions endangers the integrity of the shared data set. 

• All tasks sharing a DCB must be in the job step that opened the DCB (see "Sharing a 
Data Set"). 

• Each task sharing a DCB must ensure that all of the input and output operations it 
initiated using a given DCB are complete, before the task terminates. A CLOSE 
macro instruction issued for the DCB will ensure termination of all input and output 
operations. 

• A DCB can be closed only by the task that opened it. 
Considerations for Opening and Closing Data Sets: 

• Two or more DCBs should never be concurrently open for output to the same data set 
on a direct-access device, except with the basic indexed sequential access method 
(BISAM). Otherwise the end-of-file record written by CLOSE for one DCB may 
overlay data associated with another DCB. 

• If one DCB is concurrently open for input and one for output to the same data set on 
a direct-access device, the input DCB may be unable to read what the output DCB 
wrote if the output DCB extended the data set. 

• If you want to use the same DD statement for two or more DCBs, you cannot specify 
parameters for fields in the first DCB and then be assured of obtaining the default 
parameters for the same fields in any subsequent DCB using the same DD statement. 
This is true for both input and output and is especially important when you are using 
more than one access method. Any action on one DCB that alters the JFCB affects 
the other DCB(s) and thus can cause unpredictable results. Therefore, unless the 
parameters of all DCBs using one DD statement are the same, you should use separate 
DD statements. 

• Associated data sets for the 3525 Card Punch can be opened in any order, but all data 
sets must be opened before any processing can begin. Associated data sets can be 
closed in any order, but once a data set has been closed, I/O operations cannot be 
performed on any of the associated data sets. See OS and OS/VS Programming 
Support for the IBM 3505 Card Reader and IBM 3525 Card Punch for more 
information. 

• Volume disposition specified in the OPEN or CLOSE macro instruction can be 
overridden by the system if necessary. However, you need not be concerned; the 
system automatically requests the mounting and demounting of volumes, depending 
upon the availability of devices at a particular time. Additional information on volume 
disposition is provided in OS/VS2 JCL. 

There are two classes of errors that can occur during open, close, and end-of-volume 
processing; determinate and indeterminate errors. Determinate errors are errors 
associated with a system completion code. For example, a condition associated with 
the 213 completion code with a return code of 04 might be detected during open 
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processing, indicating that a format- 1 DSCB could not be found for a data set being 
opened. Indeterminate errors are errors that cannot be anticipated, such as a program 
check. 

If a determinate error occurs during the processing resulting from a concurrent OPEN 
or CLOSE macro instruction, an attempt will be made to complete open or close 
processing of the DCBs that are not associated with the DCB in error. Note that you 
can also choose to abnormally terminate the task immediately by coding a DCB 
ABEND exit routine that indicates the "immediate termination" option (see "DCB 
ABEND Exit"). When all open or close processing is completed, abnormal 
termination processing is begun. Abnormal termination involves forcing all DCBs 
associated with a given OPEN or CLOSE macro to close status, thereby freeing all 
storage, devices, and other system resources related to the DCBs. 

If an indeterminate error (such as a program check) occurs during open, close, or 
EOV processing, no attempt is made by the system control program to complete 
concurrent open or close processing. The DCBs associated with the OPEN or CLOSE 
macro are forced to close status if possible, and the resources related to each DCB are 
freed. 

To determine the status of any DCB after an indeterminate error, the OPEN 
(CLOSE) return code in register 15 must be interrogated for the following values: 

- All entries in the parameter list opened successfully. 

4 - All entries in the parameter list have successfully completed open, but one or more entries 

have a warning message. 

8 - One or more entries in the parameter list were not opened successfully. The entries with 

errors were restored to their pre-open status. 

12 - One or more entries in the parameter list were not opened successfully. The entries with 

errors were not restored, and cannot be reopened without restoration. 

For more information on error processing and system recovery, see OS/VS2 System 
Programming Library: Supervisor. 

During task termination the system issues a CLOSE macro for each data set which is 
still open. If this is an abnormal termination, the QSAM close routines (which would 
normally finish processing buffers) are bypassed. Any outstanding I/O requests are 
purged. Thus, your last data records may be lost for a QSAM output data set. 

It is a good procedure to close an ISAM data set before task termination because, if an 
I/O error is detected, the ISAM close routines cannot return the problem program 
registers to the SYNAD routine, causing unpredictable results. 
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OPEN — Prepare a Data Set for Processing 



The OPEN macro instruction is used to complete a data control block for an 
associated data set. The method of processing and the volume positioning 
instruction in the event of an end-of -volume condition can be specified. 

Processing Method: You can process a data set as either input or output. This 
is done by coding INPUT, OUTPUT, or EXTEND as the processing method 
operand of the OPEN macro. For BSAM, code INOUT, OUTIN, or 
OUTINX. If the data set resides on a direct-access volume, you can code 
UPDAT in the processing method operand to indicate that records can be 
updated. By coding RDBACK in this operand, you can specify that a 
magnetic-tape volume containing format-F or format-U records is to be read 
backward. Variable-length records cannot be read backward. If the processing 
method operand is omitted from the OPEN macro instruction, INPUT is 
assumed. The operand is ignored by the basic indexed sequential access 
method (BISAM); it must be specified as OUTPUT or EXTEND when you 
are using the queued indexed sequential access method (QISAM) to create an 
indexed sequential data set. You can override the INOUT, OUTIN, UPDAT, 
or OUTINX at execution by using the LABEL parameter of the DD 
statement, as discussed in OS/ VS2 JCL. 

SYSIN and SYSOUT data sets must be opened for INPUT and OUTPUT, 
respectively. INOUT is treated as INPUT, OUTIN, EXTEND, or 
OUTINX is treated as OUTPUT. UPDAT and RDBACK cannot be used. 

In Figure 28, the data sets associated with three DCBs are to be opened 
simultaneously. 

OPEN ( TEXTDCB , , CONVDCB , ( OUTPUT ) , PRINTDCB , 
( OUTPUT ) ) 

0,4Align list to fullword 
1,*+16Load regl w/list address 
AL1( 0)Option byte 
AL3( TEXTDCB )DCB address 
AL1 ( 15 )Option byte 
AL3( CONVDCB )DCB address 
AL1 ( 143 )Option byte 
AL3( PRINTDCB )DCB address 
19 Issue open SVC 

Figure 28. Opening Three Data Sets Simultaneously 

Since no processing method operand is specified for TEXTDCB, the system 
assumes INPUT. Both CONVDCB and PRINTDCB are opened for output. 
No volume positioning options are specified; thus, the disposition indicated by 
the DD statement DISP parameter is used. 

At execution, the SVC 19 instruction passes control to the Open routine, 
which then initializes the three DCBs and loads the appropriate access 
method routines. 
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CLOSE — Terminate Processing of a Data Set 



The CLOSE macro instruction is used to terminate processing of a data set 
and release it from a DCB. The volume- positioning that is to result from 
closing the data set can also be specified. Volume positioning options are the 
same as those that can be specified for end-of -volume conditions in the 
OPEN macro instruction or the DD statement. An additional volume 
positioning option, REWIND, is available and can be specified by the CLOSE 
macro instruction for magnetic-tape volumes. REWIND positions the tape at 
the load point regardless of the direction of processing. 
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You can code CLOSE TYPE=T and perform some close functions for 
sequential data sets on magnetic tape and direct-access volumes processed 
with BSAM. When you use TYPE=T, the DCB used to process the data set 
maintains its open status, and you should not issue another OPEN macro 
instruction to continue processing the same data set. This option cannot be 
used in a SYNAD routine. 

The TYPE=T operand causes the system control program to process labels, 
modify some of the fields in the system control blocks for that data set, and 
reposition the volume (or current volume in the case of multivolume data 
sets) in much the same way that the normal CLOSE macro does. When you 
code TYPE=T, you can specify that the volume either be positioned at the 
end of data (the LEAVE option) or be repositioned at the beginning of data 
(the REREAD option). Magnetic-tape volumes are repositioned either 
immediately before the first data record or immediately after the last data 
record; the presence of tape labels has no effect on repositioning. 
Figure 29, which assumes a sample data set containing 1000 records, 
illustrates the relationship between each positioning option and the point at 
which you resume processing the data set after issuing the temporary close. 

If you code the release (RLSE) operand on the DD statement for an output 
data set, it is ignored by temporary close (CLOSE TYPE=T).. If the last 
operation occurring prior to closing the data set was a write, any unused space 
will be released when you finally issue the normal CLOSE macro instruction. 

It is possible to use BSAM to process a data set that is not 
physical-sequential; if you use CLOSE TYPE=T for them, the following 
restrictions apply: 

• The DCB for the data set you are processing on a direct-access device 
must specify either DSORG=PS or DSORG=PSU for input processing, 
and either DSORG=PS, DSORG=PSU, DSORG=PO, or DSORG=POU 
for output processing. 

• The DCB must not be open for input to a member of a partitioned data 
set. 
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Figure 29. Record Processed When LEAVE or REREAD is Specified for CLOSE TYPE=T 

• If you open a data set on a direct-access device for output and issue CLOSE 
TYPE=T, the volume will be repositioned only if the data set was created with 
DSORG=PS, DSORG=PSU, DSORG=PO, or DSORG=POU (you cannot specify 
the REREAD option if DSORG=PO or DSORG=POU is specified). (This restriction 
prohibits the use of temporary close following or during the building of a BDAM data 
set that is created by specifying BSAM MACRF=WL). 

• If you open the data set for input and issue CLOSE TYPE=T with the LEAVE 
option, the volume will be repositioned only if the data set specifies DSORG=PS or 
DSORG=PO. 

Note: When a data control block is shared among multiple tasks, only the task that 
opened the data set can close it unless TYPE=T is specified. 

Before issuing the CLOSE macro, a CHECK macro must be issued for all DECBs that 
have outstanding I/O from WRITE macro instructions. When CLOSE TYPE=T is 
specified, a CHECK macro must be issued for all DECBs that have outstanding I/O 
from either WRITE or READ macro instructions. 

In Figure 30, the data sets associated with three DCBs are to be closed simultaneously. 
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Figure 30. 


Closing Three Data Sets Simultaneously 
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Because no volume positioning operands are specified, the position indicated by the DD 
statement DISP parameter is used. 

At execution, the SVC 20 instruction passes control to the Close routine, which 
terminates processing of the three data sets and returns the three DCBs to their original 
status. 

Releasing Data Sets and Volumes: You are offered the option of being able to release 
data sets and the volumes the data sets reside on when your task is no longer using them. 
Assuming that you are not sharing data sets, these data sets and the volumes on which 
they reside, would otherwise remain unavailable for use by other tasks until the job step 
that opened them is terminated. 

There are two ways to code the CLOSE macro instruction that can result in releasing a 
data set and the volume on which it resides at the time the data set is closed: 

In conjunction with the FREE=CLOSE parameter of the DD statement you can code: 

CLOSE (DCBl,DISP)or 
CLOSE (DCB 1 .REWIND) 

If you do not code FREE= CLOSE on the DD statement, you can code: 

CLOSE (DCB 1, FREE) 

See OS/VS2 JCL for information about how to use and code the FREE= CLOSE 
parameter of the DD statement. 

In either case, tape data sets and the volume on which the tape is mounted will be freed 
for use by another job step. Data sets on direct-access devices will be freed and the 
volumes on which they reside will be freed if no other data sets on the volume are open. 
Additional information on volume disposition is provided in OS/VS2 JCL. 

Data sets being temporarily closed (using CLOSE TYPE=T) cannot be released at the 
time the data set is closed. They will be released at termination of the job step. 

Refer to OS/ VS Data Management Macro Instructions for additional information and 
coding restrictions. 



End-of- Volume Processing 



Control is passed automatically to the data management end-of-volume routine when 
any of the following conditions is detected: 

• Tapemark (input tape volume) 

• Filemark or end of last extent (input direct-access volume) 

•"' End-of-data indicator (input device other than magnetic tape or direct-access 
volume). An example of this would be the last card read on a card reader. 

• End of reel (output tape volume) 

• End of extent (output direct-access volume) 

You may issue a force end-of-volume (FEOV) macro instruction before the 
end-of-volume condition is detected. 

If the LABEL parameter of the associated DD statement indicates standard labels, the 
end-of-volume routine checks or creates standard trailer labels. If SUL or AUL is 
specified, control is passed to the appropriate user label routine if it is specified in your 
exit list. 

If multiple-volume data sets are specified in your DD statement, automatic volume 
switching is accomplished by the end-of-volume routine. When an end-of-volume 
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condition exists on an output data set, additional space is allocated as indicated in your 
DD statement. If no more volumes are specified or if more than specified are required, 
the storage is obtained from any available volume on a device of the same type. If no 
such volume is available, your job is terminated. 

Volume Positioning: When an end-of-volume condition is detected, the system positions 
the volume according to the disposition specified in the DD statement unless the volume 
disposition is specified in the OPEN macro instruction. Volume positioning instructions 
for a sequential data set on magnetic tape can be specified as LEAVE or REREAD. 

LEAVE 

positions a labeled tape to the point following the tape mark that follows the data set 
trailer label group, and an unlabeled volume to the point following the tape mark that 
follows the last block of the data set. 

REREAD 

positions a labeled tape to the point preceding the data set header label group, and an 
unlabeled tape to the point preceding the first block of the data set. 

If the tape was last read backward: 

LEAVE 

positions a labeled tape to the point preceding the data set header label group, and an 
unlabeled tape to the point preceding the first block of the data set. 

REREAD 

positions a labeled tape to the point following the tape mark that follows the data set 
trailer label group, and an unlabeled tape to the point following the tape mark that 
follows the last block of the data set. 

If, however, you want to position the current volume according to the option specified in 
the DISP parameter of the DD statement, you code DISP in the OPEN macro 
instruction. 

DISP 

specifies that a tape volume is to be disposed of in the manner implied by the DD 
statement associated with the data set. Direct-access volume positioning and 
disposition are not affected by this parameter of the OPEN macro instruction. There 
are several dispositions that can be specified in the DISP parameter of the DD 
statement; DISP can be PASS, DELETE, KEEP, CATLG, or UNCATLG. 

The resultant action at the time an end-of-volume condition arises depends on (1) 
how many tape units are allocated to the data set and (2) how many volumes are 
specified for the data set in the DD statement. This is determined by the UNIT and 
VOLUME parameters of the DD statement associated with the data set. If the 
number of volumes is greater than the number of units allocated, the current volume 
will be rewound and unloaded. If the number of volumes is less than or equal to the 
number of units, the current volume is merely rewound. 

A volume positioning instruction can be specified only if the processing method 
operand has been specified. It is ignored if devices other than magnetic-tape and 
direct-access are used, or if the number of volumes exceeds the number of available 
units. 
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For magnetic-tape volumes that are not being unloaded, positioning varies according 
to the direction of the last input operation and the existence of tape labels. 

If the tape was last read forward: 

LEAVE 

positions a labeled tape to the point following the tapemark that follows the data set 
trailer label group, and an unlabeled volume to the point following the tapemark that 
follows the last block of the data set. 

REREAD 

positions a labeled tape to the point preceding the data set header label group, and an 
unlabeled tape to the point preceding the first block of the data set. 

If the tape was last read backward: 

LEAVE 

positions a labeled tape to the point preceding the data set header label group, and an 
unlabeled tape to the point preceding the first block of the data set. 

REREAD 

positions a labeled tape to the point following the tapemark that follows the data set 
trailer label group, and an unlabeled tape to the point following the tapemark that 
follows the last block of the data set. 



FEOV— Force End of Volume 



The FEOV macro instruction directs the operating system to initiate end-of-volume 
processing before the physical end of the current volume is reached. If another volume 
has been specified for the data set, volume switching takes place automatically. The 
volume positioning options REWIND and LEAVE are available. 

If an FEOV macro is issued for a spanned multivolume data set which is being read using 
QSAM, errors may occur when the next GET macro is issued. These errors are 
documented in the section, "Spanned Variable-Length Records" in "Part 1: Introduction 
to Data Management." 

The FEOV macro instruction can only be used when you are using BSAM or QSAM. 
FEOV is ignored if issued for a SYSIN or SYSOUT data set. 



Buffer Acquisition and Control 



The operating system provides several methods of buffer acquisition and control. Each 
buffer (virtual-storage area used for intermediate storage of input/output data) usually 
corresponds in length to the size of a block in the data set being processed. When you 
use the queued access technique, any reference to a buffer actually refers to the next 
record {buffer segment). 

You can assign more than one buffer to a data set by associating the buffer with a buffer 
pool. A buffer pool must be constructed in a virtual-storage area allocated for a given 
number of buffers of a given length. 

The number of buffers you assign to a data set should be a tradeoff against the frequency 
with which you refer to each buffer. A buffer that is not referred to for a relatively long 
period of time may be paged out. If this were allowed to happen to any considerable 
degree, it could result in a greater number of buffers actually decreasing throughput. 

Buffer segments and buffers within the buffer pool are controlled automatically by the 
system when the queued access technique is used. However, you can terminate 
processing of a buffer by issuing a release (RELSE) macro instruction for input or a 
truncate (TRUNC) macro instruction for output. Two buffering techniques, simple and 
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exchange, can be used to process a sequential data set. Only simple buffering can be used 
to process an indexed sequential data set. 

If you use the basic access technique, you can use buffers as work areas rather than as 
intermediate storage areas. You can control them directly, by using the GETBUF and 
FREEBUF macro instructions, or dynamically for BDAM and BISAM, by requesting 
dynamic buffering in your DCB macro instruction and your READ or WRITE macro 
instruction. If you request dynamic buffering, the system will automatically provide a 
buffer each time a READ macro instruction is issued. That buffer will be freed when you 
issue a WRITE or FREEDBUF macro instruction. 

Buffer Pool Construction 

Buffer pool construction can be accomplished in any of three ways: 

• Statically using the BUILD macro instruction 

• Explicitly using the GETPOOL macro instruction 

• Automatically by the system when the data set is opened 

If QSAM simple buffering is used, the buffers are automatically returned to the pool 
when the data set is closed. If the buffer pool is constructed explicitly or automatically, 
the virtual storage area must be returned to the system by the FREEPOOL macro 
instruction. 

In many applications, fullword or doubleword alignment of a block within a buffer is 
important. You can specify in the DCB that buffers are to start on either a doubleword 
boundary or a fullword boundary that is not also a doubleword boundary (by coding 
BFALN=D or F). If doubleword alignment is specified for format- V records, the fifth 
byte of the first record in the block is so aligned. For that reason, fullword alignment 
must be requested to align the first byte of the variable-length record on a doubleword 
boundary. The alignment of the records following the first in the block depends on the 
length of the previous records. 

Note that buffer alignment provides alignment only for the buffer. If records from ASCII 
magnetic tape are read and the records use the block prefix, the boundary alignment of 
logical records within the buffer depends on the length of the block prefix. If the length 
is 4, logical records are on fullword boundaries. If the length is 8, logical records are on 
doubleword boundaries. 

If the BUILD macro instruction is used to construct the buffer pool, alignment depends 
on the alignment of the first byte of the reserved storage area. 

When you process multiple QISAM data sets, you can use a common buffer pool. To do 
this, however, you must use the BUILD macro instruction to reformat the buffer pool 
before opening each data set. 

BUILD-— Construct a Buffer Pool 

When you know, before program assembly, both the number and the size of the buffers 
required for a given data set, you can reserve an area of appropriate size to be used as a 
buffer pool. Any type of area can be used — for example, a predefined storage area or an 
area of coding no longer needed. 

A BUILD macro instruction, issued during execution of your program, structures the 
reserved storage area into a buffer pool. The address of the buffer pool must be the same 
as that specified for the buffer pool control block (BUFCB) in your DCB. The buffer 
pool control block is an 8-byte field preceding the buffers in the buffer pool. The number 
(BUFNO) and length (BUFL) of the buffers must also be specified. For QSAM, the 
length of BUFL must be at least the blocksize. 
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When the data set using the buffer pool is closed, you can reuse the area as required. 
You can also reissue the BUILD macro instruction to reconstruct the area into a new 
buffer pool to be used by another data set. 

You can assign the buffer pool to two or more data sets that require buffers of the same 
length. To do this, you must construct an area large enough to accommodate the total 
number of buffers required at any one time during execution. That is, if each of two data 
sets requires five buffers (BUFNO=5), the BUILD macro instruction should specify ten 
buffers. The area must also be large enough to contain the 8-byte buffer pool control 
block. 



BUILDRCD — Build a Buffer Pool and a Record Area 



The BUILDRCD macro instruction, like the BUILD macro instruction, causes a buffer 
pool to be constructed in an area of virtual storage you provide. In addition, BUILDRCD 
makes it possible for you to access variable-length, spanned records as complete logical 
records, rather than as segments. 

You must be processing with QSAM in the locate mode and you must be processing 
either VS or VBS records, if you want to access the variable-length, spanned records as 
logical records. If you issue the BUILDRCD macro before the data set is opened, or 
during your DCB exit routine, you automatically get logical records rather than segments 
of spanned records. 

Only one logical record storage area is built, no matter how many buffers are specified; 
therefore, you can't share the buffer pool with other data sets that may be open at the 
same time. 



GETPOOL— Get a Buffer Pool 



If a specified area is not reserved for use as a buffer pool, or you want to defer specifying 
the number and length of the buffers until execution of your program, you should use the 
GETPOOL macro instruction. It enables you to vary the size and number of buffers 
according to the needs of the data set being processed. 

The GETPOOL macro instruction structures a virtual-storage area allocated by the 
system into a buffer pool, assigns a buffer pool control block, and associates the pool 
with a specific data set. The GETPOOL macro instruction should be issued either before 
opening of the data set or during your DCB exit routine. 

When using GETPOOL with QSAM, specify a buffer length (BUFL) of at least as large 
as the blocksize. 



Automatic Buffer Pool Construction 



If you have requested a buffer pool and have not used an appropriate macro instruction 
by the end of your DCB exit routine, the system automatically allocates virtual-storage 
space for a buffer pool. The buffer pool control block is also assigned and the pool is 
associated with a specific DCB. For BSAM, a buffer pool is requested by specifying 
BUFNO. For QSAM, BUFNO can be specified or allowed to default to 5. If 
you are using the basic access technique to process an indexed sequential or direct data 
set, you must indicate dynamic buffer control. Otherwise, the system does not construct 
the buffer pool automatically. 

Because a buffer pool obtained automatically is not freed automatically when you issue a 
CLOSE macro instruction, you should also issue a FREEPOOL or FREEMAIN macro 
instruction, which is discussed in the next section. 
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FREEPOOL — Free a Buffer Pool 



Any buffer pool assigned to a DCB either automatically by the OPEN macro instruction 
(except when dynamic buffer control is used) or explicitly by the GETPOOL macro 
instruction should be released before your program is terminated. The FREEPOOL 
macro instruction should be issued to release the virtual-storage area as soon as the 
buffers are no longer needed. When you are using the queued access technique, a data 
set must be closed first. When you are using exchange buffering, the buffer pool must 
not be released until all the data sets have been closed. 

If the OPEN macro was issued while running under a protect key of zero, a buffer pool 
which was obtained by OPEN should be released by issuing the FREEMAIN macro 
instead of the FREEPOOL macro. This is necessary because the buffer pool acquired 
under these conditions will be in storage assigned to subpool 252. 

Constructing a Buffer Pool: Figures 31 and 32 illustrate several possible methods of 
constructing a buffer pool. They do not take into account the method of processing or 
controlling the buffers in the pool. 

In Figure 31, a static storage area named INPOOL is allocated during program assembly. 
The BUILD macro instruction, issued during execution, arranges the buffer pool into ten 
buffers, each 52 bytes long. Five buffers are assigned to INDCB and five to OUTDCB, 
as specified in the DCB macro instruction for each. The two data sets share the buffer 
pool because both specify INPOOL as the buffer pool control block. Notice that an 
additional 8 bytes have been allocated for the buffer pool to contain the buffer pool 
control block. The 4-byte chain pointer which occupies the first four bytes of the buffer 
is included in the buffer, so no allowance need be made for this field. 

In Figure 32, two buffer pools are constructed explicitly by the GETPOOL macro 
instructions. Ten input buffers are provided, each 52 bytes long, to contain one 
fixed-length record; five output buffers are provided, each 112 bytes long, to contain two 
blocked records plus an 8-byte count field (required by ISAM). Notice that both data 
sets are closed before the buffer pools are released by the FREEPOOL macro 
instructions. The same procedure should be used if the buffer pools were constructed 
automatically by the OPEN macro instruction. 



Buffer Control 



Your program can use four techniques to control the buffers used by your program. The 
advantages of each depend to a great extent upon the type of job you are doing. Simple 
and exchange buffering are provided for the queued access technique. The basic access 
technique provides for either direct or dynamic buffer control. 
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Figure 31. Constructing a Buffer Pool From a Static Storage Area 
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Figure 32. Constructing a Buffer Pool Using GETPOOL and FREEPOOL 



Although only simple buffering can be used to process an indexed sequential data set, 
buffer segments and buffers within a buffer pool are controlled automatically by the 
operating system. 

In addition, the queued access technique provides four processing modes that determine 
the extent of data movement in virtual storage. Move, data, locate, or substitute mode 
processing can be specified for either the GET or PUT macro instruction. The buffer 
processing mode is specified in the MACRF field of the DCB macro instruction. The 
movement of a record is determined as follows: 

• Move mode: The record is moved from an input buffer to your work area, or from 
your work area to an output buffer. 

• Data mode (QSAM format-V spanned records only): The same as the move mode 
except only the data portion of the record is moved. 

• Locate mode: The record is not moved. Instead, the address of the next input or 
output buffer is placed in register 1. For QSAM format-V spanned records, if you 
have specified logical records by specifying BFTEK=A or by issuing the BUILDRCD 
macro instruction, the address returned in register 1 points to a record area where the 
spanned record is assembled or segmented. 

The PUT-locate routine uses the value in the DCBLRECL field to determine whether 
another record will fit into your buffer. Therefore, when you write a short record, you 
can maximize the number of records per block by modifying the DCBLRECL field 
before you issue a PUT-locate to get a buffer segment for the short record. The 
processing sequence follows: 

1 . Register 1 is returned to you with the address of the next buffer segment. 

2. Move the record into the output buffer segment. 

3. Put the length of the next (short) record into DCBLRECL. 

4. Issue PUT-locate. 

5. Move the short record into the buffer segment. 

• Substitute mode: Move mode is used when substitute mode is requested in MVS. 

Two processing modes of the PUTX macro instruction can be used in conjunction with a 
GET-locate macro instruction. The update mode returns an updated record to the data 
set from which it was read; the output mode transfers an updated record to an output 
data set. There is no actual movement of data in virtual storage. The processing mode is 
specified by the operand of the PUTX macro instruction, as explained in OS/VS2 MVS 
Data Management Macro Instructions. 
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If you use the basic access technique, you can control buffers in one of two ways: 

• Directly, using the GETBUF macro instruction to retrieve a buffer constructed as 
described above. A buffer can then be returned to the pool by the FREEBUF macro 
instruction. 
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• Dynamically, by requesting a dynamic buffer in your READ or WRITE macro 

instruction. This technique can be used only when you are using BIS AM or BDAM. If 
you request dynamic buffering, the system automatically provides a buffer each time a 
READ macro instruction is issued. The buffer is supplied from a buffer pool that is 
created by the system when the data set is opened. The buffer is released (returned to 
the pool) upon completion of a WRITE macro instruction when you are updating. If 
you do not update the record in the buffer and thus release the buffer when the record 
is written, the FREEDBUF macro instruction may be used. If you are processing an 
indexed sequential data set, the buffer is automatically released upon the next issuance 
of the READ macro instruction if there has been no intervening WRITE or 
FREEDBUF macro instruction. 



The term simple buffering refers to the relationship of segments within the buffer. All 
segments in a simple buffer are together in storage and are always associated with the 
same data set. When the buffer pool is constructed, the system creates a channel 
command word (CCW) for each buffer in the buffer pool. For this reason, each record 
must be physically moved from an input buffer segment to an output buffer segment. It 
can be processed within either segment or in a work area. 

If you use simple buffering, records of any format can be processed. New records can be 
inserted and old records deleted as required to create a new data set. A record can be 
moved and processed as follows: 

• Processed in an input buffer and then moved to an output buffer (GET-locate, 
PUT-move/PUTX-output) 

• Moved from an input buffer to an output buffer where it can be processed 
(GET-move, PUT-locate) 

• Moved from an input buffer to a work area where it can be processed and then moved 
to an output buffer (GET-move, PUT-move) 

• Processed in an input buffer and returned to the data set (GET-locate, PUTX-update) 

The following examples illustrate the control of simple buffers and the processing modes 
that can be used. The buffer pools may have been constructed in any way previously 
described. 

Simple Buffering— GET-locate, PUT-move/PUTX-output: The GET macro instruction 
(step A, Figure 33) locates the next input record to be processed. Its address is returned 
in register 1 by the system. The address is passed to the PUT macro instruction in 
register 0. 

The PUT macro instruction (step B, Figure 33) specifies the address of the record in 
register 0. The system then moves the record to the next output buffer. 

Note: The PUTX-output macro instruction can be used in place of the PUT-move macro 
instruction. However, processing will be as described under exchange buffering (see 
PUT-substitute). 

Simple Buffering — GET-move, PUT-locate: The PUT macro instruction locates the 
address of the next available output buffer. Its address is returned in register 1 and is 
passed to the GET macro instruction in register 0. 

The GET macro instruction specifies the address of the output buffer into which the 
system moves the next input record. 

A filled output buffer is not written until the next PUT macro instruction is issued. 
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Figure 33. Simple Buffering with MACRF=GL and MACRF=PM 



Simple Buffering — GET-move, PUT-move: The GET macro instruction (step A, Figure 

34) specifies the address of a work area into which the system moves the next record 
from the input buffer. 

The PUT macro instruction (step B, Figure 34) specifies the address of a work area from 
which the system moves the record into the next output buffer. 

Simple Buffering — GET-locate, PUT-locate: The GET macro instruction (step A, Figure 

35) locates the address of the next available input buffer. The address is returned in 
register 1. 

The PUT macro instruction (step B, Figure 35) locates the address of the next available 
output buffer. Its address is returned in register 1 . You must then move the record from 
the input buffer to the output buffer (step C, Figure 35). Processing can be done either 
before or after the move operation. 

A filled output buffer is not written until the next PUT macro instruction is issued. The 
CLOSE and FEOV macro instructions write the last record of your data set by issuing 
TRUNC and PUT macro instructions. Be careful not to issue an extra PUT before 
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Figure 34. Simple Buffering with MACRF=GM and MACRF=PM 
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Figure 35. Simple Buffering with MACRF=GL and MACRF=PL 



issuing CLOSE or FEOV. Otherwise, when the CLOSE or FEOV macro instruction tries 
to write your last record, the extra PUT will write a meaningless record or produce a 
sequence error. 

Note that if records other than format-F records are being moved, the length attribute of 
the MVC instruction must be changed as shown by the code beginning with the USING 
statement in Figure 35. If the record is more than 256 bytes, you can code a move 
routine or use a MVCL instruction to process the complete record. 

Simple Buffering-UPDAT Mode: When a data set is opened with UPDAT specified 
(Figure 36), only GET-locate and PUTX-update are supported. The GET macro locates 
the next input record to be processed and its address is returned in register 1 by the 
system. The user may update the record and issue a PUTX macro which will cause the 
block to be written back in its original location in the data set after all the logical records 
in that block have been processed. 
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(No movement of data takes place) 
Figure 36. Simple Buffering with MACRF=GL and MACRF=PM-UPDAT Mode 
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Exchange Buffering 



Exchange buffering is not supported in MVS. Its request is ignored by the system and 
move mode is used instead. 

Buffering Techniques and GET/PUT Processing Modes: As you can see from the 
previous examples, the most efficient code is achieved by use of automatic buffer pool 
construction, and GET-locate and PUTX-output with simple buffering. Figure 37 
summarizes the combinations of buffering techniques and processing modes that 
can be used. 



RELSE — Release an Input Buffer 



When using the queued access technique to process a sequential or indexed sequential 
data set, you can direct the system to ignore the remaining records in the input buffer 
being processed. The next GET macro instruction retrieves a record from another buffer. 
If format-V spanned records are being used, the next logical record obtained may begin 
on any segment in any subsequent block. 

If you are using move mode, the buffer is made available for refilling as soon as the 
RELSE macro instruction is issued. When you are using locate mode, the system does 
not refill the buffer until the next GET macro instruction is issued. If a PUTX macro 
instruction has been used, the block is written before the buffer is refilled. 
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Figure 37. Buffering Technique and GET/PUT Processing Modes 
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TRUNC — Truncate an Output Buffer 



When using the queued access technique to process a sequential data set, you can direct 
the system to write a short block. The first record in the next buffer is the next record 
processed by a PUT-output or PUTX-output mode. 

If the locate mode is being used, the system assumes that a record has been placed in the 
buffer segment pointed to by the last PUT macro instruction. 

The last block of a data set is truncated by the Close routine. Note that a data set 
containing format-F records with truncated blocks cannot be read from direct-access 
storage as efficiently as a standard format-F data set. 



GETBUF — Get a Buffer from a Pool 



The GETBUF macro instruction can be used with the basic access technique to request a 
buffer from a buffer pool constructed by the BUILD, GETPOOL, or OPEN macro 
instruction. The address of the buffer is returned by the system in a register you specify 
when you issue the macro instruction. If no buffer is available, the register contains 
instead of an address. 



FREEBUF— Return a Buffer to a Pool 



The FREEBUF macro instruction is used with the basic access technique to return a 
buffer to the buffer pool from which it was obtained by a GETBUF macro instruction. 
Although the buffers need not be returned in the order in which they were obtained, they 
must be returned when they are no longer needed. 



FREEDBUF — Return a Dynamic Buffer to a Pool 



Any buffer obtained through the dynamic buffer option must be released before it can be 
used again. When you are processing a direct data set, if you do not update the block in 
the buffer and thus free the buffer when the block is written, you must use the 
FREEDBUF macro instruction. If there is an uncorrectable input/output error, the 
control program releases the buffer. When you are processing an indexed sequential data 
set, if you do not update the block in the buffer or if there is an uncorrectable input 
error, the control program releases the buffer when the next READ macro instruction is 
issued on the same DECB, unless you use the FREEDBUF macro instruction. 

To effect the release, you must specify the address of the DECB that was used when the 
block was read using the dynamic buffering option, as well as the address of the DCB 
associated with the data set being processed. 



Processing a Sequential Data Set 



Data sets residing on all volumes other than direct-access volumes must be processed 
sequentially. In addition, a data set residing on a direct-access volume, regardless of 
organization, can be processed sequentially. This includes data sets created using ISAM 
or a similar access method. Since the entire data set (prime, index, and overflow areas) 
will be processed, care should be taken to determine the type of records being processed. 
This feature of the operating system allows you to write your program with little regard 
for the type of device to be used when the program is executed, except for restrictions on 
the use of certain device-dependent macro instructions and processing options. 

Either the queued or the basic access technique may be used to store and retrieve the 
records of a sequential data set. Additionally, a technique called chained scheduling can 
be used to accelerate the input/output operations required for a sequential data set 
(residing on nondirect-access devices for 5740-AM3). 
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Data Format — Device Type Considerations 



Magnetic Tape (TA) 



Before execution of your program, you must supply the operating system with both the 
record format (RECFM) and device-dependent (DEVD) information in a DCB macro 
instruction, a DD statement, or a data set label. The DCB subparameters for the DD 
statement differ slightly from those described here. A complete description of the DD 
statement and a glossary of DCB subparameters are contained in OS/VS2 JCL. 

The record format (RECFM) parameter of the DCB macro instruction specifies the 
characteristics of the records in the data set as fixed-length (RECFM=F), 
variable-length (RECFM =V or D), or undefined-length (RECFM =U). Fixed-length 
blocked records (RECFM=FB) can be specified as standard (RECFM=FBS), which 
means there are no truncated (short) blocks or unfilled tracks within the data set, with 
the possible exception of the last block or track. Data sets with a fixed-length, standard 
format were described previously under "Fixed-Length Records, Standard Format." 

As an optional feature, a control character can be contained in each record. This control 
character will be recognized and processed if the data set is printed or punched. The 
control characters are transmitted on both tapes and direct-access volumes. The presence 
of a control character is indicated by M or A in the RECFM field of the data control 
block. M denotes machine code; A denotes American National Standards Institute 
(ANSI) code. If either M or A is specified, the character must be present in every record; 
the printer space (PRTSP) or stacker select (STACK) field of the DCB is ignored. The 
optional control character must be in the first byte of format-F and format-U records 
and in the fifth byte of format-V records and format-D records where BUFOFF=L. 
Control character codes are listed in "Appendix B: Control Characters." The 
device-dependent (DEVD) parameter of the DCB macro instruction specifies the type of 
device on which the data set's volume resides: 

TA magnetic tape 

PT paper tape reader 

PR printer 

PC card punch 

RD card reader 

DA direct-access device or 

Mass Storage System (MSS) virtual volumes 



Format-F, V, D, and U records are acceptable for magnetic tape. Format-V records are 
not acceptable on 7 -track tape if the data conversion feature is not available. ASCII 
records are not acceptable on 7 -track tape. 

When you create a tape data set with variable-length record format (V or D), the control 
program pads any data block shorter than 18 bytes. For format-V records, it pads to the 
right with binary zeros so that the data block length equals 18 bytes. For format-D 
(ASCII) records, the padding consists of ASCII circumflex characters which are 
equivalent to X'5E's. 

Note that there is no minimum requirement for blocksize; however, if a data check 
occurs on a magnetic-tape device, any record shorter than 12 bytes in a read operation or 
1 8 bytes in a write operation will be treated as a noise record and lost. No check for 
noise will be made unless a data check occurs. 

Tape density (DEN) specifies the recording density in bits per inch per track, as shown 
in Figure 38. If this information is not supplied, the highest applicable density is assumed. 
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Recording Density 




DEN 7-Track Tape 

200 

1 556 

2 800 

3 — 

4 — 


9-Track Tape 

800 (NRZI) 
1600 (PE) 
6250 (GCR) 



NRZI is for non-return-to-zero-inverted mode 

PE is for phase encoded mode 

GCR is for group coded recording mode 

Specifying DEN=0 for a 7-track 3420 tape attached to a 3803-1 will result in 556 bits per inch recording, 
but corresponding messages and tape labels will indicate 200 bits per inch recording density. 

Figure 38. Tape Density (DEN) Values 

The track recording technique (TRTCH) for 7-track tape can be specified as: 

C Data conversion is to be used. Data conversion makes it possible to write 8 binary 
bits of data on 7 tracks. Otherwise, only 6 bits of an 8-bit byte are recorded. The 
length field of format-V records contains binary data and is not recorded correctly 
without data conversion. 

E Even parity is to be used; if E is omitted, odd parity is assumed. 

T BCDIC to EBCDIC translation is required. 



Paper-Tape Reader (PT) 



The paper-tape reader accepts format-F and format-U records. If you use QSAM, you 
should not specify the records as blocked. Each format-U record is followed by an 
end-of -record character. Data read from paper tape may optionally be converted into the 
System/370 internal representation of one of six standard paper-tape codes. Any 
character found to have a parity error will not be converted when the record is 
transferred into the input area. Characters deleted in the conversion process are not 
counted in determining the block size. 

The following symbols indicate the code in which the data was punched. If this 
information is omitted, I is assumed. 

I IBM BCD perforated tape and transmission code (8 tracks) 

F Friden (8 tracks) 

B Burroughs (7 tracks) 

C National Cash Register (8 tracks) 

A ASCII (8 tracks) 

T Teletype* (5 tracks) 

N No conversion 

Note that when you are using QSAM, the processing mode must be move mode. 



Card Reader and Punch (RD/PC) 



Format-F and U records are acceptable to both the reader and punch; format-V records 
are acceptable to the punch only. The device control character, if specified in the 
RECFM parameter, is used to select the stacker; it is not punched. The first 4 bytes 
(record descriptor word or segment descriptor word) of format-V records or record 
segments are not punched. For format-V records, at least 1 byte of data must follow the 
record or segment descriptor word or the carriage control character. 



* Trademark of the Teletype Corporation 



Part 2: Data Management Processing Procedures 85 



Page of GC26-3875-0 
Revised June 29, 1979 
By TNL GN26-0944 



Each punched card corresponds to one physical record. Therefore, you should restrict the 
maximum record size to 80 (EBCDIC mode) or 160 (column binary mode) data bytes. 
When mode (C) is used for the card punch, BLKSIZE must be 160 unless you are using 
PUT. Then you can specify BLKSIZE as 160 or a multiple of 160, and the system 
handles this as described earlier under "PUT — Write a Record" in the section "Queued 
Access Techniques." You can specify the read/punch mode of operation (MODE) 
parameter as either card image (column binary) mode (C) or EBCDIC mode (E). If this 
information is omitted, E is assumed. The stacker selection parameter (STACK) can be 
specified as either 1 or 2 to indicate which bin is to receive the card. If it is not specified, 
1 is assumed. 

For all QSAM, RECFM=FB, card punch data sets, the block size in the DCB will be 
adjusted by the system to equal the logical record length. This data set will be treated as 
RECFM=F. If the system builds the buffers for this data set, the buffer length will be 
determined by the BUFL parameter. If the BUFL parameter was not specified, the 
adjusted block size is used for the buffer length. 

If the DCB is to be reused with a block size larger than the logical record length, you 
must reset DCBBLKSI in the DCB and ensure that the buffers are large enough to 
contain the largest block size expected. You may ensure the buffer size by specifying the 
BUFL parameter before the first time the data set is opened or by issuing the 
FREEPOOL macro instruction after each CLOSE macro so the system will build a new 
buffer pool of the correct size each time the data set is opened. 

Punch error correction on the IBM 2540 Card Read Punch is not performed when using 
MVS. 

The 3525 Card Punch accepts only format-F records for print data sets and for 
associated data sets. Other record formats are allowed for the read data set, the punch 
data set, and the interpret punch data set. See OS and OS/VS Programming Support 
for the IBM 3505 Card Reader and IBM 3525 Card Punch for more information on 
programming for the 3525 Card Punch. 



Printer (PR) 



Records of format-F, V, and U are acceptable to the printer. The first 4 bytes (record 
descriptor word or segment descriptor word) of format-V records or record segments are 
not printed. For format-V records, at least 1 byte of data must follow the record or 
segment descriptor word or the carriage control character. The carriage control 
character, if specified in the RECFM parameter, is not printed. The system does not 
position the printer to channel 1 for the first record unless specified by a carriage control 
character. 

Because each line of print corresponds to one record, the record length should not 
exceed the length of one line on the printer. For variable-length spanned records, each 
line corresponds to one record segment, and blocksize should not exceed the length of 
one line on the printer. 

If carriage control characters are not specified, you can indicate printer spacing (PRTSP) 
as 0, 1, 2, or 3. If it is not specified, 1 is assumed. 

For all QSAM, RECFM=FB, printer data sets, the block size in the DCB will be 
adjusted by the system to equal the logical record length. This data set will be treated as 
RECFM=F. If the system builds the buffers for this data set, the buffer length will be 
determined by the BUFL parameter. If the BUFL parameter was not specified, the 
adjusted block size is used for the buffer length. 

If the DCB is to be reused with a block size larger than the logical record length, you 
must reset DCBBLKSI in the DCB and insure that the buffers are large enough to 
contain the largest block size expected. You may insure the buffer size by specifying the 
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BUFL parameter before the first time the data set is opened or by issuing the 
FREEPOOL macro instruction after each CLOSE macro so the system will build a new 
buffer pool of the correct size each time the data set is opened. 



Direct-Access Device (DA) 



Direct-access devices accept records of format-F, V, or U. If the records are to be read 
or written with keys, the key length (KEYLEN) must be specified. In addition, the 
operating system has a standard track format for all direct access volumes. Each track 
contains data information as well as certain control information such as: 

• The address of the track 

• The address of each record 

• The length of each record 

• Gaps between areas 

A complete description of track format is contained in the section "Direct-Access Device 
Characteristics." Your only concern in creating a sequential data set is to allow for an 
8-byte track descriptor record (capacity record or RO) when requesting space on a 
direct-access volume. In addition, device overhead, which varies with the device, must be 
allocated for each block on the track. 



Device Control 



The operating system provides you with six macro instructions for controlling 
input/output devices. Each is, to varying degrees, device-dependent. Therefore, you 
must exercise some care if you wish to achieve device independence. 

When you use the queued access technique, only unit record equipment can be controlled 
directly. When using the basic access technique, limited device independence can be 
achieved between magnetic-tape and direct-access devices. You must check all read or 
write operations before issuing a device control macro instruction. 

CNTRL — Control an I/O Device 

The CNTRL macro instruction performs these device-dependent control functions: 

Card reader stacker selection (SS) 

Printer line spacing (SP) 

Printer carriage control (SK) 

Magnetic-tape backspace (BSR) over a specified number of blocks 

Magnetic-tape backspace (BSM) past a tapemark and forward space over the 
tapemark 

Magnetic-tape forward space (FSR) over a specified number of blocks 

Magnetic-tape forward space (FSM) past a tapemark and a backspace over the 
tapemark 

Backspacing moves the tape toward the load point; forward spacing moves the tape away 
from the load point. 

Note that the CNTRL macro instruction cannot be used with an input data set 
containing variable-length records on the card reader. 

You can use the CNTRL macro instruction to position DOS tapes that contain 
embedded DOS checkpoint records if you specify OPTCD=H in the DCB parameter 
field of the DD statement. The CNTRL macro instruction cannot be used to backspace 
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DOS 7-track tapes that are written in data convert mode and contain embedded 
checkpoint records. 



PRTOV— Test for Printer Overflow 



The PRTOV macro instruction tests for channel 9 or 12 of the printer carriage control 
tape or the forms control buffer (FCB). An overflow condition causes either an 
automatic skip to channel 1 or, if specified, transfer of control to your routine for 
overflow processing. If you specify an overflow exit routine, set DCBIFLGS to X'OO' 
before issuing another PRTOV. 



If the data set specified in the DCB is not for a printer, no action is taken. 



SETPRT— Printer Setup 



The SETPRT macro instruction is used to initially set or dynamically change the 
specifications of the 3800 Printing Subsystem. The SETPRT macro instruction is also 
used to dynamically change the specifications of the 3203 or 3211 printers or the 1403 
printer with UCS. For additional information on how to use the SETPRT macro with the 
3800 printer, see IBM 3800 Printing Subsystem Programmer's Guide. 

For printers that have a universal character set (UCS) buffer or a forms control buffer 
(FCB), the SETPRT macro instruction is used to fetch UCS and FCB images from the 
image library (SYS1.IMAGELIB) and load them into their respective buffers. Note that 
FCB images for the 3203, 3211, and 3800 are not compatible. The universal character 
sets for the 1403, 3203, or 3211 and the character arrangement tables for the 3800 are 
also incompatible. 

The SETPRT macro allows you to request the operator to verify loading of the buffer. 
For the 1403, 3203, and 3211 printers, the SETPRT macro allows you to specify the 
printing of lowercase EBCDIC characters in uppercase when no uppercase/lowercase 
print chain or train is available. 

For a printer that has no carriage control tape, you can use the SETPRT macro 
instruction to load the FCB, to request operator verification of buffer loading, and to 
allow the operator to align the paper in the printer. 

The FCB contents can be fetched from the system library or defined in your program 
through the exit list of the DCB macro instruction, as discussed under "Exit List 
(EXLST)." 

When issued, the SETPRT macro instruction can load the UCS buffer from the system 
library. The library contains images of standard IBM character sets and of your own 
special character sets. The operator can be requested to verify the loaded image after 
mounting the appropriate print chain or train. 

The SETPRT macro instruction can be used to block or unblock printer data checks. 
When data checks are blocked, unprintable characters are treated as blanks and do not 
cause an error condition. 

Except for the 3800, if the specified UCS or FCB image is not found in the image library 
(or DCB exit list for an FCB image), the operator is requested to specify a different one 
(message IEC127D is issued). If the operator is unable to supply a valid name, or the 
device is a 3800, the SETPRT macro will give an error return code. 
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BSP — Backspace a Magnetic Tape or Direct- Access Volume 



The BSP macro instruction backspaces one block on the magnetic tape or direct-access 
volume being processed. The block can then be reread or rewritten. An attempt to 
rewrite the block destroys the contents of the remainder of the tape or track. 

The direction of movement is toward the load point or beginning of the extent. You may 
not use the BSP macro instruction if the track overflow option was specified or if the 
CNTRL, NOTE, or POINT macro instruction is used. The BSP macro instruction should 
be used only when other device control macro instructions could not be used for 
backspacing. 

Any attempt to backspace across a file mark will result in a return code of X'04' and 
your tape or direct-access volume will be positioned after the file mark. This means you 
cannot issue a successful backspace command once your EODAD routine is entered 
unless you first reposition the tape or direct-access volume into your data set. (CLOSE 
TYPE=T can get you positioned at the end of your data set.) 

You can use the BSP macro instruction to backspace DOS tapes containing embedded 
DOS checkpoint records. If you use this means of backspacing, you must test for and 
bypass the embedded checkpoint records. You cannot use the BSP macro instruction for 
DOS 7-track tapes written in translate mode. 



NOTE — Return the Relative Address of a Block 



The NOTE macro instruction requests the relative address of the block just read or 
written. In a multivolume data set, the address is relative to the beginning of the volume 
currently being processed. 

The address provided by the operating system is returned in register 1. The address is in 
the form of a 4-byte relative block address for magnetic tape; for a direct-access device, 
it is a 4-byte relative track address. The amount of unused space available on the track of 
the direct-access device is returned in register 0. 



POINT— Position to a Block 



The POINT macro instruction causes repositioning of a magnetic tape or direct-access 
volume to a specified block. The next read or write operation begins at this block. In a 
multivolume data set, you must ensure that the volume referred to is the volume 
currently being processed. If a write operation follows the POINT macro instruction, all 
of the track following the write operation is erased unless the data set is opened for 
UPDAT. POINT is not meant to be used before a WRITE macro instruction when a data 
set is opened for UPDAT. You can use the POINT macro instruction to position DOS 
tapes that contain embedded checkpoint records if you specify OPTCD=H in the DCB 
parameter field of the DD statement. The POINT macro instruction cannot be used to 
backspace DOS 7-track tapes that are written in data convert mode and contain 
embedded checkpoint records. 

When using the POINT macro for a direct-access device that is opened for OUTPUT, 
OUTIN, or INOUT, and the record format is not standard, the number of blocks per 
track may vary slightly. 
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Device Independence 



The ability to request input/output operations without regard for the physical 
characteristics of the I/O devices makes it possible for you to write one program that will 
fulfill a variety of needs. Device independence may be useful for: 

• Accepting data from a number of recording devices, such as a disk pack, 7- or 9-track 
magnetic tape, or unit-record equipment. This situation could arise when several types 
of data-acquisition devices are feeding a centralized complex. 

• Observing constraints imposed by the availability of input/output devices (for 
example, when devices on order have not been installed). 

• Assembling, testing, and debugging on one System/370 configuration and processing 
on a different configuration. For example, a 2314 drive can be used as a substitute for 
several magnetic-tape units. 

Device independence is not difficult to achieve, but requires some planning and 
forethought. There are two areas of planning necessary to achieve device 
independence — system generation considerations and programming considerations. 



System Generation Considerations 



You can provide for device independence when the system is generated by generating a 
system that not only meets the current input/output configuration requirements but 
includes anticipated device attachments. Creating such a system entails looking ahead at 
expected delivery of input/output devices and, during system generation, constructing 
the necessary control blocks and tables. Thus, when the devices are delivered, they need 
only be physically attached. The operating system recognizes the devices without 
modification. However, until the devices are physically connected, the operator must 
designate them as being offline, using the VARY command, unless 
OPTIONS =DE VST AT was specified on the CTRLPROG macro during system 
generation. For information on the CTRLPROG macro, see OS/VS2 System 
Programming Library: System Generation Reference. 

When new device attachments cannot be fully anticipated, you can add new devices by 
performing an I/O device generation. This is a limited type of system generation that 
enables you to change your I/O configuration without regenerating other parts of the 
system. 

System generation techniques for effecting a smooth transition to new input/output 
devices do not include addition of new device types. When support for new devices is 
provided, a new system must be generated. A complete description of system generation 
techniques is contained in OS/ VS2 System Programming Library: System Generation 
Reference. 
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Programming Considerations 



Each of three data set organizations — partitioned, indexed sequential, and 
direct — requires the use of a direct-access device. Device independence is meaningful, 
then, only for a sequentially organized data set, that is, a data set where one block of 
data follows another, thus allowing input or output to be on a magnetic tape drive, a 
direct-access device, a card read/punch, a printer, or a spooled data set. 

Your program will be device-independent if you do two things: 

• Omit all device-dependent macro instructions and macro instruction parameters from 
your program. 

• Defer specifying any required device-dependent parameters until the program is ready 
for execution. That is, supply the parameters on your data definition (DD) statement 
or during the open exit routine. 

In examining the following list of macro instructions, consider only the logical layout of 
your data record without regard for the type of device used. Also, consider that any 
reference to a direct-access volume is to be treated like a reference to magnetic tape, that 
is, you must create a new data set rather than attempt to update. 

OPEN 

Specify INPUT, OUTPUT, INOUT, OUTIN, OUTINX, or EXTEND. The 
parameters RDBACK and UPDAT are device-dependent and cause an 
abnormal termination if directed to a device of the wrong type. 

READ 

Specify forward reading (SF) only. 

WRITE 

Specify forward writing (SF) only; use only to create new records. 

PUTX 

Use only output mode. 

NOTE/POINT 

These macros are valid for both magnetic-tape and direct-access volumes. 

BSP 

This macro is valid for magnetic-tape or direct-access volumes. However, its use 
would be an attempt to perform device-dependent action. 

CNTRL/PRTOV 

These macros are device-dependent. 

DCB Subparameters 

MACRF 

Specify R/W or G/P. Processing mode can also be indicated. 

DEVD 

Specify DA if any direct-access device may be used. Magnetic-tape and unit-record 
equipment DCBs will fit in the area provided during assembly. Specify unit-record 
devices only if you expect never to change to tape or direct-access devices. Key length 
(KEYLEN) can be specified on the DD statement if necessary. 

RECFM, LRECL, BLKSIZE 

These can be specified in the DD statement. However, you must consider maximum 
record size for specific devices, and track overflow cannot be specified unless 
supported. 

DSORG 

Specify sequential organization (PS or PSU). 
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OPTCD 

This subparameter is device-dependent; specify it in the DD statement. 

SYNAD 

Any device-dependent error checking is automatic. Generalize your routine so that no 
device-dependent information is required. 

Chained Scheduling for I/O Operations (including Nondirect-Access 
Devices for 5740-AM3 only) 

To accelerate the input/output operations required for a data set, the operating system 
provides a technique called chained scheduling. When requested, the system bypasses 
the normal I/O routines and dynamically chains several input/output operations 
together. A series of separate read or write operations, functioning with chained 
scheduling, is issued to the computing system as one continuous operation. In a 
nonpageable partition or address space, the program-controlled interruption (PCI) flag in 
the CCWs is used for synchronization of the I/O operations. 

The I/O performance is improved by reduction in both the CPU time and the channel 
start/stop time required to transfer data within virtual storage. Some factors that affect 
performance improvement are: 

• Address space type (real or virtual) 
. BUFNOforQSAM 

• The number of overlapped requests for BSAM 

• Other activity on the CPU and channel 

The effects of rotational delay are also reduced, since several successive blocks, requested 
separately, can be retrieved in a single rotation. Chained scheduling can be used only 
with simple buffering. Each data set for which chained scheduling is specified must be 
assigned at least two and preferably three buffers with QSAM, or must have a value of at 
least two and preferably three for NCP with BSAM or BPAM. 

Chained scheduling will be used by MVS whether it is requested or not (except for 
printers and format-U input records). Chained scheduling will not be used where it is not 
allowed. 

For 5740-AM3, the following two paragraphs replace the paragraph above: 

The system will default to chained scheduling for nondirect-access devices (other than 
printers and format-U records on nondirect-access devices) except for those cases in 
which it is not allowed. 

A request for exchange buffering in MVS is not honored, but compatibly defaults to 
move mode and therefore has no effect on either a request for chained scheduling or 
a default to chained scheduling. 
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A request for chained scheduling will be ignored and normal scheduling used 
if any of the following are encountered when the data set is opened: 

Direct Access Device (5740-AM3 only; 

Search Direct (This line is deleted by 5740-AM3) 

BDAM CREATE, that is, MACRF=(WL) (This line is deleted by 
5740-AM3) 

Track overflow 

UPDAT in the operand of the OPEN macro instruction 

CNTRL macro instruction to be used 

Device type is paper tape reader 

Bypassing of embedded DOS checkpoint records on tape input data sets 

Spooled data sets (SYSIN or SYSOUT) 

A print data set or any associated data set for the 3525 Card Punch. (See OS and 
OS/VS Programming Support for the IBM 3505 Card Reader and IBM 3525 
Card Punch for more information on programming for the 3525.) 

The number of channel program segments that can be chained is limited to the value 
specified in the NCP operand of BSAM and BPAM DCBs, and to the value specified in 
the BUFNO operand of QSAM DCBs. 

Chained scheduling should not be specified (DCB=OPTCD=C) when channel 9 or 
channel 12 is in the carriage control tape. 

When chained scheduling is being used, the automatic skip feature of the PRTOV macro 
instruction for the printer will not function. Format control must be achieved by ANSI or 
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machine control characters. (Control characters are discussed in more detail in Part 1 
under "Control Character," in Part 2 under "Data Format — Device Type 
Considerations," and in "Appendix B: Control Characters.") When you read 
undefined-length records with QSAM, the DCBLRECL field is equal to the BLKSIZE 
field, not the actual record length. The entire block is moved to your work area in the 
move mode. When you are using QSAM under chained scheduling to read 
variable-length, blocked, ASCII tape records (format-DB), you must code BUFOFF=L 
in the DCB for that data set. 

Note also that if you are using BSAM with the chained scheduling option to read 
format-DB records and have coded a value for the BUFOFF operand other than 
BUFOFF=L, the input buffers will be converted from ASCII to EBCDIC as usual, but 
the record length returned to the DCBLRECL field will equal the block size, not the 
actual length of the record read in; the record descriptor word (RDW), if present, will 
not have been converted from ASCII to binary. 

A request for the chained scheduling technique overrides a request for the search direct 
technique. If you request both techniques, or if chained scheduling is defaulted and 
search direct is requested, then chained scheduling is used. 

Chained scheduling is most valuable for programs that require extensive input and output 
operations. Because a data set using chained scheduling may monopolize available time 
on a channel in a V=R region, separate channels should be assigned, if possible, when 
more than one data set is to be processed. 

Search Direct for Input Operations (Except 5740-AM3) 

To accelerate the input operations required for a data set on DASD, the operating system 
provides a technique called search direct. Search direct reads in the requested record and 
the count field of the second record. This allows the operation to get the next record 
directly, along with the count field of the following record. Search direct can be used 
with all record formats except format-UT, format-FBT, format-FS, format-FBS, and 
spanned. You request search direct by coding OPTCD=Z in the DCB macro instruction. 
For FS and FBS records, the access method routines always use a form of search-direct 
processing. Search direct cannot be used under the following conditions: 

• In conjunction with the NOTE and POINT macro instructions 

• When you specify the UPDAT option of the OPEN macro instruction 

• For partitioned data sets 

| • When chained scheduling is used 

Search Direct for Input Operations (5740-AM3 only) 

To accelerate the input operations required for a data set on DASD, the operating system 
provides a technique called search direct. Search direct reads in the requested record and 
the count field of the second record. This allows the operation to get the next record 
directly, along with the count field of the following record. 

The function provided by the search-direct option is supplied whether or not it is 
requested. OPTCD=Z need not be coded and if used is ignored. 

Except under the following conditions: 

• In conjunction with the NOTE and POINT macro instructions 

• When you specify the UPDAT option of the OPEN macro instruction 
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• For partitioned data sets 

• When chained scheduling is used 

you may receive unpredictable results when your application runs on a system with the 
Sequential Access Method-Extended (SAM-E) installed and your application has a 
dependency that prevents the use of search direct. For example, you may receive 
unpredictable results when multiple DCBs are open for a file and one of the applications 
is updating or adding records. 



Creating a Sequential Data Set 



As discussed earlier, a processing program should be developed using, as much as 
possible, factors that are constant, with variable factors specified at execution. For that 
reason, the following examples are generalized as much as possible. They are neither 
exhaustive nor intended as complete examples. Rather, they are presented as 
introductory sequences. 

In creating a sequential data set on a magnetic tape or direct-access device, you must do 
the following: 

• Code DSORG=PS or PSU in the DCB macro instruction 

• Code a DD statement to describe the data set (See OS/VS2 JCL.) 

• Process the data set with an OPEN macro instruction (data set is opened for output or 
OUTIN), a series of PUT or WRITE and CHECK macros, and then a CLOSE macro 

Tape-to-Print, Move Mode — Simple Buffering: In Figure 39, the GET-move and 
PUT-move require two movements of the data records. If the record length (LRECL) 
does not change in processing, only one move is necessary; you can process the record in 
the input buffer segment. A GET-locate can be used to provide a pointer to the current 
segment. 

Tape-to-Print, Locate Mode — Simple Buffering: This example (Figure 40) is similar to 
that in Figure 39. However, since there is no change in the record length, the records can 
be processed in the input buffer. Only one move of each data record is required. 



NEXTREC 



TAPERROR 



ENDJOB 

WORKAREA 
COUNT 
NUMBER 
SAVE 14 
INDATA 

OUTDATA 



OPEN 

GET 

AP 

UNPK 

PUT 

B 

SYNADAF 

LA 

ST 

PUT 

SYNADRLS 

L 

RETURN 

CLOSE 



( INDATA, , OUTDATA, ( OUTPUT ) ) 

INDATA , WORKAREA 

NUMBER, =P r 1 ' 

COUNT, NUMBER 

OUTDATA, COUNT 

NEXTREC 

ACSMETH=QSAM 

0,68(0,1 ) 

14,SAVE14 

OUTDATA, (0 ) 

14,SAVE14 

( INDATA , , OUTDATA ) 



Move mode 

Record count adds 6 
bytes to each record 

Control program returns message 
address in register 1 . 
SYNAD routine prints part of 
the message ( beginning with 
the unit number ) as a 56-byte 
fixed- length record. It then 
returns to the control 
program. 



DS CL50 

DS CL6 

DC PL4 ' ' 

DS F 

DCB DDNAME=INPUTDD , DSORG=PS , MACRF=( GM ) , EROPT=ACC , 

S YNAD=TAPERROR , EODAD=END JOB 

DCB DDNAME=OUTPUTDD , DSORG=PS , MACRF= ( PM ) , EROPT=ACC 



Figure 39. Creating a Sequential Data Set — Move Mode, Simple Buffering 
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Process the data set with an OPEN macro instruction (data set is opened for input, 
INOUT, RDBACK, or UPDAT), a series of GET or READ macros and then a 
CLOSE macro. 



Updating a Sequential Data Set 



When you update in place, you read records, process them, and write them back to their 
original positions without destroying the remaining records on the track. The following 
rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro instruction. To 
perform the update, you can use only the READ, WRITE, CHECK, NOTE, POINT, 
GET, and PUTX macro instructions. 

• You cannot use chained scheduling. 
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( INDATA, , OUTDATA, , ERRORDCB ) 



( OUTPUT ) , ERRORDCB, ( OUTPUT ) ) 
Locate mode 
Save pointer 



Process in input area 

Locate mode 

Move record to output buffer 

Message address in register 1 
Save register 2 contents 
Load pointer to input buffer 
Shift nonblank message fields 
Blank end of message 

Save address for debugging 
Test SYNADAF return code 
Branch if data read 
Branch if data not read 
See if data read anyway 
Branch if definitely no data 
Add input record to message 
Load address of message 
Save return address 
Print message (move mode) 
Release message and save area 
Restore return address 
Restore register 2 contents 
Return to control program 



DC PL4 ' ' 

DCB DDNAME=INPUTDD , DSORG=PS , MACRF= ( GL ) , EROPT=ACC , 

S YNAD=TAPERROR , EODAD=ENDJOB 
DCB DDNAME=OUTPUTDD , DSORG=PS , MACRF= ( PL ) 
DCB DDNAME=S YSOUTDD , DSORG=PS , MACRF= ( PM ) , RECFM=V , 

BLKSIZE=128,LRECL=124 
DS F 



Figure 40. Creating a Sequential Data Set — Locate Mode, Simple Buffering 



Retrieving a Sequential Data Set 



In retrieving a sequential data set on a magnetic tape or direct-access device, you must 
do the following: 

• Code DSORG=PS or PSU in the DCB macro instruction 

• Tell the system where your data set is located (by coding a DD statement; see 
OS/VS2 JCL). 

• Process the data set with an OPEN macro instruction (data set is opened for input, 
INOUT, RDBACK, or UPDAT), a series of GET or READ macros and then a 
CLOSE macro. 



Updating a Sequential Data Set 



When you update in place, you read records, process them, and write them back to their 
original positions without destroying the remaining records on the track. The following 
rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro instruction. To 
perform the update, you can use only the READ, WRITE, CHECK, NOTE, POINT, 
GET, and PUTX macro instructions. 

• You cannot use chained scheduling. 
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• You cannot delete any record or change its length; you cannot add new records. 

• The data set must be on a direct-access device. 

A record must be retrieved by a READ or GET macro instruction before it can be 
updated by a WRITE or PUTX macro instruction. A WRITE or PUTX macro 
instruction does not need to be issued after each READ or GET macro instruction. The 
READ and WRITE macro instructions must be execute forms that refer to the same 
DECB; the DECB must be provided by the list forms of the READ or WRITE macro 
instructions. (The execute and list forms of the READ and WRITE macro instructions 
are described in OS/VS2 MVS Data Management Macro Instructions.) 

Updating With Overlapped Operations: To overlap input/output and CPU activity, you 
can start several read or write operations before checking the first for completion. You 
cannot overlap read with write operations, however, as operations of one type are started 
or resumed. Note that each concurrent read or write operation requires a separate 
channel program and a separate DECB. If a single DECB were used for successive read 
operations, only the last record read could be updated. 

In Figure 50, overlap is achieved by having a read or write request outstanding while 
each record is being processed. Note the use of the execute and list forms Of the READ 
and WRITE macro instructions, identified by the operands MF=E and MF=L. 

Extending a Sequential Data Set 

If you want to add records at the end of your data set, you must open the data set for 
output with DISP=MOD specified in the DD statement or specify the EXTEND option 
of the OPEN macro. You can then issue PUT or WRITE macros to the data set. 

Determining the Length of a Record When Using the BSAM READ Macro 

When you read a sequential data set, you can determine the length of the record in one 
of the following four ways, depending upon the record format of the data set: 

• For fixed-length, unblocked records, the length of all records is the value in the 
DCBBLKSI field of the DCB. 

• For variable-length records, the block descriptor word in the record contains the 
length of the record. 

• For fixed-length blocked or undefined-length records, the following method can be 
used to calculate the block length. (This method should not be used when reading 
track overflow records on a device with the rotational position sensing (RPS) feature 

I or when using chained scheduling with format U records. In these cases, the length of 
a record cannot be determined.) (For 5740-AM3 only, this method should not be 
used for chained scheduling on non-direct access devices. The length of a record 
cannot be determined when using chained scheduling.) After checking the DECB for 
the READ request but before issuing any subsequent data management macro 
instructions that specify the DCB for the READ request, obtain the IOB address from 
the DECB. The IOB address can be loaded from the location 16 bytes from the start 
of the DECB. 

Obtain the residual count from the channel status word (CSW) that has been stored in 
the input/output block (IOB). The residual count is in the half word 14 bytes from the 
start of the IOB. Subtract this residual count from the number of data bytes requested 
to be read by the READ macro instruction. If "S" was coded as the length parameter 
of the READ macro instruction, the number of bytes requested is the value of 
DCBBLKSI at the time the READ was issued. If the length was coded in the READ 
macro instruction, this value is the number of data bytes and it is contained in the 
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halfword 6 bytes from the beginning of the DECB. The result of the subtraction is the 
length of the block read. See Figure 41. 

• Except for 5740- AM3, for undefined-length records, the LRECL operand should be 
omitted; the actual length can be supplied dynamically in a READ/WRITE macro 
instruction. (This method should not be used when reading track overflow records on 
a device with the rotational position sensing (RPS) feature or when using chained 
scheduling on any device.) When an undefined-length record is read, the actual length 
of the record is returned by the system in the DCBLRECL field of the data control 
block. 

• For 5740-AM3, when an undefined-length record is read, the actual length of the 
record is returned in the DCBLRECL field of the data control block. Because of this 
use of DCBLRECL, the LRECL operand should be omitted. The length to be read or 
written can be supplied dynamically in a READ/WRITE macro instruction using 
BSAM. This method cannot be used when using chained scheduling on any non-direct 
access device. 

Writing a Short Block When Using the BSAM WRITE Macro 

When you are writing blocks for a sequential data set, you can change the length of a 
block if you have fixed-blocked record format. The DCB block size field (DCBBLKSI) 
can be changed to specify a block size that is shorter than what was originally specified 
for the data set. The DCBBLKSI field must be changed before issuing the WRITE macro 
instruction and must be a multiple of the LRECL parameter in the DCB. Any 
subsequent WRITE macro instructions issued will write records with the new block 
length until the block size is changed again. The DCB block size field should not be 
changed to specify a block size that is greater than what was originally specified for the 
data set. 
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OPEN(DCB,( INPUT) ) 
LA DCBR,DCB 

USING IHADCB,DCBR 

READ DECB1 , SF, DCB, AREA1 , 'S' 
READ DECB2,SF,DCB,AREA2,50 
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CHECK DECB2 

LH W0RK1 ,DECB2+6 

L WORK2,DECB2+16 

SH W0RK1 , 14(WORK2 ) 

MVC DCBBLKSI,LENGTH3 

READ DECB3,SF,DCB,AREA3 

CHECK DECB3 

LH WORK 1 , LENGTH 3 

L WORK2,DECB+16 

SH W0RK1 , 14(W0RK2 ) 
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.RECFM=U,NCP=2, 



Figure 41. One Method of Determining the Length of the Record When Using BSAM to Read Undefined-Length Records 



Processing a Partitioned Data Set 



A partitioned data set can be stored only on a direct-access device. It is divided into 
sequentially organized members, each made up of one or more records (see Figure 42). 
Each member has a unique name, 1 to 8 characters long, stored in a directory that is part 
of the data set. The records of a given member are stored or retrieved sequentially. 
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Figure 42. A Partitioned Data Set 
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The main advantage of using a partitioned data set is that you can retrieve any individual 
member once the data set is opened without searching the entire data set. For example, a 
program library can be stored as a partitioned data set, each member of which is a 
separate program or subroutine. The individual members can be added or deleted as 
required. When a member is deleted, the member name is removed from the directory, 
but the space used by the member cannot be reused until the data set is reorganized. 

The directory, a series of records at the beginning of the data set, contains an entry for 
each member. Each directory entry contains the member name and the starting location 
of the member within the data set, as shown in Figure 42. In addition, you can specify up 
to 62 characters of information in the entry. The directory entries are arranged in 
alphameric collating sequence by name. 

The track address of each member is recorded by the system as a relative track address 
within the data set rather than as an absolute track address. Thus, an entire data set can 
be moved without changing the relative track addresses in the directory. The data set can 
be considered as one continuous set of tracks regardless of how the space was actually 
allocated. 

If there is not sufficient space available in the directory for an additional entry, or not 
enough space available within the data set for an additional member, no new members 
can be stored. 



Partitioned Data Set Directory 



The directory of a partitioned data set occupies the beginning of the area allocated to the 
data set on a direct-access volume. It is searched and maintained by the FIND and 
STOW macro instructions. The directory consists of member entries arranged in 
ascending order according to the binary value of the member name or alias. 

Member entries vary in length and are blocked into 256-byte blocks. Each block 
contains as many complete entries as will fit in a maximum of 254 bytes; any remaining 
bytes are left unused and are ignored. Each directory block contains a 2-byte count field 
that specifies the number of active bytes in a block (including the count field). As shown 
in Figure 43, each block is preceded by a hardware-defined key field containing the 
name of the last member entry in the block, that is, the member name with the highest 
binary value. 

Each member entry contains a member name or alias. Each entry also contains the 
relative track address of the member and a count field, as shown in Figure 44. In 
addition, it may contain a user data field. The last entry in the last directory block has a 
name field of maximum binary value — all Is. 

NAME 

specifies the member name or alias. It contains up to 8 alphameric characters, 
left-justified and padded with blanks if necessary. 



Count 



Key 




Name of 
Last 

Entry in 
Block 



Bytes 



8 



Data 



Number of 

Bytes Used 

(Maximum 

256) 


Member 
Entry A 


Member 
Entry B 



Member 
Entry N 



SiUnused: 



254 



Figure 43. A Partitioned Data Set Directory Block 
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Member 
Name 



TTR 



Optional User Data 



TTRN 



Pointer to 
First Record 
of Member 



TTRN 



TTRN 



0-31 half words 
(Maximum 62 bytes) 



Bits 



1 1f 

Name is an 
Alias 


Number of 

User Data 

TTRNs 


Number of User 
Data Halfwords 



1-2 



3-7 



Figure 44. A Partitioned Data Set Directory Entry 



TTR 



is a pointer to the first block of the member; TT is the number of the track, relative to 
the beginning of the data set, and R is the number of the block, relative to the 
beginning of that track. 

Note: This pointer is created by adding 1 to the TTR for the last block of the 
previous member (which is an end-of-file mark). If track TT is full, the next block will 
begin at record 1 of track TT + 1 , and the pointer will be updated accordingly. The 
control program finds the block by searching in multitrack mode using TT(R-l) as a 
search argument. 

specifies the number of halfwords contained in the user data field. It may also contain 
additional information about the user data field, as shown below: 

Bits 






1-2 


3-7 









when set to 1 , indicates that the NAME field contains an alias. 

1-2 specifies the number of pointers to locations within the member. 

A maximum of three pointers is allowed in the user data field. Additional pointers 
may be contained in a record referred to as a note list, discussed below. The 
pointers can be updated automatically if the data set is moved or copied by a utility 
program such as IEHMOVE. The data set must be marked unmovable under the 
following conditions: 

• More than three pointers are used in the user data field. 

• The pointers in the user data field or note list do not conform to the standard 
format. 

• The pointers are not placed first in the user data field. 

• Any direct access address (absolute or relative) is embedded in any data blocks 
or in another data set that refers to this data set. 

3-7 contains a binary value indicating the number of halfwords of user data. This 
number must include the space used by pointers in the user data field. 
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You can use the user data field to provide variable data as input to the STOW macro 
instruction. If pointers to locations within the member are provided, they must be 4 bytes 
long and placed first in the user data field. The user data field format is as follows: 

User Data 



TTRN 


TTRN 


TTRN 


Optional 



TT is the relative track address of the note list or area to which you are pointing. 

R is the relative block number on that track. 

N is a binary value that indicates the number of additional pointers contained in a 
note list pointed to by the TTR. If the pointer is not to a note list, N=0. 

A note list consists of additional pointers to blocks within the same member of a 
partitioned data set. You can divide a member into subgroups and store a pointer to the 
beginning of each subgroup in the note list. The member may be a load module 
containing many control sections (CSECTs), each GSECT being a subgroup pointed to 
by an entry in the note list. You get the pointer to the beginning of the subgroup by 
using the NOTE macro instruction after you write the first record of the subgroup. 
Remember that the pointer to the first record of the member is stored in the directory 
entry by the system. 

If the existence of a note list was indicated as shown above, the list can be updated 
automatically when the data set is moved or copied by a utility program such as 
IEHMOVE. Each 4-byte entry in the note list has the following format: 



TTRX 



TT is the relative track address of the area to which you are pointing. 

R is the relative block number on that track. 

X is available for any use. 

To place the note list in the partitioned data set, you must use the WRITE macro 
instruction. After checking the write operation, use the NOTE macro instruction to 
determine the address of the list and place that address in the user data field of the 
directory entry. 



Processing a Member of a Partitioned Data Set 



Because a member of a partitioned data set is sequentially organized, it is processed in 
the same manner as a sequential data set. Either the basic or queued access technique 
can be used. However, you cannot alter the directory when using the queued technique. 

To locate a member or to process the directory, several macro instructions are provided 
by the operating system. The BLDL macro instruction can be used to structure a list of 
directory entries in virtual storage; the FIND macro instruction locates a member of the 
data set for subsequent processing; the STOW macro instruction adds, deletes, replaces, 
or changes a member name in the directory. To use these macro instructions, you must 
specify DSORG=PO or POU in the DCB macro instruction. Before issuing a FIND, 
BLDL, or STOW macro instruction, you must check all preceding input/output 
operations for completion. 
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BLDL — Construct a Directory Entry List 



The BLDL macro instruction is used to place directory information in virtual storage. 
The data is placed in a build list, which you construct before the BLDL macro instruction 
is issued. The format of the list is similar to that of the directory. For each member name 
in the list, the system supplies the address of the member and any additional information 
contained in the directory entry. Note that if there is more than one member name in the 
list, the member names must be in collating sequence regardless of whether the members 
are from the same library or from different libraries. 

You can optimize retrieval time by directing a subsequent FIND macro instruction to the, 
build list rather than the directory to locate the member to be processed. 

The build list, as shown in Figure 45, must be preceded by a 4-byte list description that 
indicates the number of entries in the list and the length of each entry (12 to 76 bytes). 
The first 8 bytes of each entry contain the member name or alias. The next 6 bytes must 
be available to contain the starting address of the member plus some control data. If 
there is no user data entry, only the TTR and C fields are required. If additional 
information is to be supplied from the directory, up to 62 bytes can be reserved. 



FIND — ^Position to a Member 



To determine the starting address of a specific member, you must issue a FIND macro 
instruction. The system places the correct address in the data control block so that a 
subsequent input or output operation begins processing at that point. 

There are two ways you can direct the system to the right member when you use the 
FIND macro instruction: specify the address of an area containing the name of the 
member or specify the address of the TTR field of the entry in a build list you have 
created by using the BLDL macro instruction. In the first case, the system searches the 
directory of the data set for the relative track address; in the second case, no search is 
required because the relative track address is in the build list entry. 



List 
Description 



FFLL 



(Each entry starts on halfword boundary) 

Filled in by BLDL 



Member 
Name (C) 



TTR 
(3) 



K 
(1) 



Z 
(1) 



c 
(1) 



1/ 

User Data 
(C Halfwords) 




Programmer Supplies: 

FF Number of member entries in list. 

LL Even number giving byte length of each entry (minimum of 12). 
Member name Eight bytes, left-justified. 



BLDL Supplies: 

TTR Member starting location. 

If only data set = 0. If concatenation = number 

Not required if no user data. 

Source of directory entry. Private library = 0. 

Link library = 1. Job or step library = 2. 

Not required if no user data. 

Same C field from directory. 

As much as will fit in entry. 

Figure 45. Build List Format 



K 



C 
User data 



Gives number of user data halfwords. 
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The system will also search a concatenated series of directories when (1) a DCB is 
supplied that is opened for a concatenated partitioned data set of (2) a DCB is not 
supplied, in which case either JOBLEB or STEPLIB (themselves perhaps concatenated) 
followed by LINKLIB is searched. 

If you want to process only one member, you can process it as a sequential data set 
(DSORG=PS) using either BSAM or QSAM. You indicate the name of the member you 
want to process and the name of the partitioned data set in the DSNAME parameter of 
the DD statement. When you open the data set, the system places the starting address in 
the data control block so that a subsequent GET or READ macro instruction begins 
processing at that point. You cannot use the FIND, BLDL, or STOW macro instructions 
when you are processing one member as a sequential data set. 

Since the DCBRELAD address in the data control block is updated when the FIND 
macro is used, you should not issue the FIND macro after WRITE and STOW processing 
without first closing the data set and reopening it for INPUT processing. 



STOW— Update the Directory 



When you add several members to a partitioned data set, you must issue a STOW macro 
instruction after writing each member so that an entry for each one will be added to the 
directory. To use the STOW macro instruction, DSORG=PO or POU must be specified 
in the DCB macro instruction. 

You can also use the STOW macro instruction to delete, replace, or change a member 
name in the directory, as well as to store additional information with the directory entry. 
Since an alias can also be stored in the directory the same way, you should be consistent 
in altering all names associated with a given member. For example, if you replace a 
member, you must delete related alias entries or change them so that they point to the 
new member. 

If you add only one member to a partitioned data set and indicate the member name in 
the DSNAME parameter of the DD statement, it is not necessary for you to use BPAM 
and a STOW macro instruction in your program. If you wish to do so, you may use 
BPAM and STOW, or BSAM or QSAM. If you use a sequential access method, or if you 
use BPAM and issue a CLOSE macro instruction without issuing a STOW macro 
instruction, the system will issue a STOW macro instruction using the member name you 
have specified on the DD statement. When the system issues the STOW, the directory 
entry that is added is the minimum length (12 bytes). This automatic STOW macro 
instruction will not be issued if the CLOSE macro instruction is a TYPE=T or if the 
TCB indicates the task is being abnormally terminated when the DCB is being closed. 
The DISP parameter on the DD statement determines what directory action parameter 
will be chosen by the system for the STOW macro instruction. 

If DISP=NEW or MOD was specified, a STOW macro instruction with the add option 
will be issued. If the member name on the DD statement is not present in the data set 
directory, it will be added. If the member name is already present in the directory, the 
task will be abnormally terminated. 

If DISP=OLD was specified, a STOW macro instruction with the replace option will be 
issued. The member name will be inserted into the directory, either as an addition if the 
name is not already present or as a replacement if the name is present. 

Thus, with an existing data set, you should use DISP,=OLD to force a member into the 
data set; you should use DISP=MOD to add members with protection against the 
accidental destruction of an existing member. 
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If you have no need to add entries to the directory, that is, the STOW and BLDL macro 
instructions will not be used, you can create a new data set and write the first member as 
follows (see Figure 46): 

• Code DSORG=PS or DSORG=PSU in the DCB macro instruction. 

• Indicate in the DD statement that the data is to be stored as a member of a new 
partitioned data set, that is, DSNAME=name (membername) and DISP=NEW. 

• Request space for the member and the directory in the DD statement. 
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• Process the member with an OPEN macro instruction, a series of PUT or WRITE 
macro instructions, and then a CLOSE macro instruction. A STOW macro instruction 
is issued automatically when the data set is closed. 

As a result of these steps, the data set and its directory are created, the records of the 
member are written, and a 12-byte entry is made in the directory. 

To add additional members to the data set, follow the same procedure. However, a 
separate DD statement (with the space request omitted) is required for each member. 
The disposition should be specified as modify, DISP=MOD. The data set must be closed 
and reopened each time a new member is specified. 

To take full advantage of the STOW macro instruction, and thus the BLDL and FIND 
macro instructions in future processing, you can provide additional information with each 
directory entry. You do this by using the basic access technique, which also allows you to 
process more than one member without closing and reopening the data set, as follows 
(see Figure 47): 

• Request space in the DD statement for the members and the directory. 

• Define DSORG=PO or DSORG=POU in the DCB macro instruction. 

• Use WRITE and CHECK to write and check the member records. 

• Use NOTE to note the location of any note list written within the member, if there is 
a note list. 



//PDSDD DD 



,DSNAME=MASTFILE(MEMBERK),SPACE=(TRK,( 100,5,7 ) ), 

DISP=( NEW, KEEP) 



OUTDCB DCB — , DSORG=PS , DDNAME=PDSDD , 

OPEN (OUTDCB, (OUTPUT) ) 
PUT [or WRITE] 



CLOSE ( OUTDCB ) 

Figure 46. Creating One Member of a Partitioned Data Set 



Automatic Stow 
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//PDSDD 
OUTDCB 



DD --,DSNAME=MASTFILE,SPACE=(TRK,( 100,5,7 ) ),DISP=MOD 

DCB — ,DSORG=PO,DDNAME=PDSDD,-- 
OPEN ( OUTDCB, ( OUTPUT ) ) 

WRITE ** Write and check first record of member. 
CHECK The system will supply the relative 

track address for the directory entry. 
WRITE Write and check remaining records of 

CHECK member. 

NOTE If you are dividing the member into 

ST subgroups, note the location of the first 

record in subgroup, storing pointer 

in note list. 
WRITE Write note list at end of member. 

CHECK 

NOTE Note location of note list, storing 

ST pointer in list for STOW. 

STOW Enter information in directory for 

this member after all records and note 

lists are written. 



Repeat from ** for each additional member 

CLOSE (OUTDCB) 
Figure 47. Creating Members of a Partitioned Data Set Using STOW 



• When all the member records have been written, issue a STOW macro instruction to 
enter the member name, its location pointer, and any additional data in the directory. 

• Continue to write, check, note, and stow until all the members of the data set and the 
directory entries have been written. 



Retrieving a Member of a Partitioned Data Set 



To retrieve a specific member from a partitioned data set, either the basic or queued 
access technique can be used as follows (see Figure 48): 

• Code DSORG=PS or DSORG=PSU in the DCB macro instruction. 

• Indicate in the DD statement that the data is a member of an existing partitioned data 
set by coding DSNAME=name(membername) and DISP=OLD. 

• Process the member with an OPEN macro instruction, a series of GET and READ 
macro instructions, and then a CLOSE macro instruction. 



//PDSDD 
INDCB 



DD 



DCB 

OPEN ( INDCB ) 
GET ( or READ ) 
CLOSE ( INDCB ) 



— , DSNAME=MASTFILE( MEMBERK ) , DISP=OLD 
— , DSORG=PS , DDNAME=PDSDD , -- 



Automatic Find 



Figure 48. Retrieving One Member of a Partitioned Data Set 



When your program is executed, the directory is searched automatically and the location 
of the member is placed in the DCB. 

To process several members without closing and reopening, or to take advantage of 
additional data in the directory, this technique should be used (see Figure 49): 

• Code DSORG=PO or POU in the DCB macro instruction. 
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• Build a list (BLDL) of needed member entries from the directory. 

• Indicate in the DD statement the data set name of the partitioned data set by coding 
DSNAME=name and DISP=OLD. 

• Use the FIND or POINT macro instruction to prepare for reading the member 
records. 

• The records may be read from the beginning of the member, or a note list may be read 
first, to obtain additional locations that point to subcategories within the member. 

• Read (and check) the records until all those required have been processed. 

• Point to additional categories, if required, and read the records. 

• Repeat this procedure for each member to be retrieved. 

//PDSDD DD — ,DSNAME=MASTFILE,DISP=OLD 

INDCB DCB --,DSORG=PO,DDNAME=PDSDD,-- 

OPEN ( INDCB ) 

BLDL Build a list of selected member names 

in virtual storage. 

FIND (or POINT) 
**Read note list. 

READ 

CHECK 

POINT Locate subgroup by using note list. 

READ 

CHECK Read member records . 

Repeat from ** for each additional member. 

CLOSE ( INDCB ) 

Figure 49. Retrieving Several Members of a Partitioned Data Set Using BLDL, FIND, and POINT 



Updating a Member of a Partitioned Data Set 



Updating in Place 



A member of a partitioned data set can be updated in place, or can be deleted and 
rewritten as a new member. 



When you update in place, you read records, process them, and write them back to their 
original positions without destroying the remaining records on the track. The following 
rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro instruction. To 
perform the update, you can use only the READ, WRITE, CHECK, NOTE, POINT, 
FIND, and BLDL macro instructions. 

• You cannot update concatenated partitioned data sets. 

• You cannot use chained scheduling. 

• You cannot delete any record or change its length; you cannot add new records. 

A record must be retrieved by a READ macro instruction before it can be updated by a 
WRITE macro instruction. Both macro instructions must be execute forms that refer to 
the same DECB; the DECB must be provided by a list form. (The execute and list forms 
of the READ and WRITE macro instructions are described in OS/VS2 MVS Data 
Management Macro Instructions.) 



Part 2: Data Management Processing Procedures 105 



Rewriting a Member 



Updating With QSAM: You can update a member of a partitioned data set using the 
locate mode of QSAM (DCB specifies MACRF=PL) and using the PUTX macro 
instruction. The DD statement must specify the data set and member name in the 
DSNAME parameter. This method allows only the updating of the member specified in 
the DD statement. 

Updating With Overlapped Operations: To overlap input/output and CPU activity, you 
can start several read or write operations before checking the first for completion. You 
cannot overlap read and write operations, however, as operations of one type must be 
checked for completion before operations of the other type are started or resumed. Note 
that each concurrent read or write operation requires a separate channel program and a 
separate DECB. If a single DECB were used for successive read operations, only the last 
record read could be updated. 

In Figure 50, overlap is achieved by having a read or write request outstanding while 
each record is being processed. Note the use of the execute and list forms of the READ 
and WRITE macro instructions, identified by the operands MF=E and MF=L. 



There is no actual update option that can be used to add or extend records in a 
partitioned data set. If you want to extend or add a record within a member, you must 
rewrite the complete member in another area of the data set. Since space is allocated 
when the data set is created, there is no need to request additional space. Note, however, 
that a partitioned data set must be contained on one volume. If sufficient space has not 



//PDSDD DD 



DSNAME=MASTFILE( MEMBERK ) , DISP=OLD , 



UPDATDCB DCB 
READ 
READ 
AREAA DS 
AREAB DS 



DSORG=PS , DDNAME=PDSDD , MACRF=( R , W ) , NCP=2 , EODAD=FINISH 
DECBA, SF, UPDATDCB, AREAA, MF=L Define DECBA 
DECBB,SF, UPDATDCB, AREAB ,MF=L Define DECBB 
Define buffers 



OPEN 
LA 
LA 
READRECD READ 
NEXTRECD READ 
CHECK 



( UPDATDCB , UPDAT 

2 , DECBA 

3, DECBB 

( 2 ),SF,MF=E 

( 3 ),SF,MF=E 

(2) 



(If update is required, branch to R2UPDATE) 



LR 
LR 
LR 
B 



4,3 
3,2 
2,4 
NEXTRECD 



Open for update 
Load DECB addresses 

Read a record 

Read the next record 

Check previous read operation 

If no update is required, 
switch DECB addresses in 
registers 2 and 3 
and loop 



In the following statements, "R2" and "R3" refer to the records that were read using the DECBs whose addresses are in 
registers 2 and 3, respectively. Either register may point to either DECBA or DECBB. 



R2UPDATE CALL UPDATE , ( ( 2 ) ) 

CHECK ( 3 ) 

WRITE (2),SF,MF=E 

(If R3 requires an update, branch to R3UPDATE) 





CHECK 


(2) 




B 


READRECD 


R3UPDAT 


ECALL 


UPDATE , ( ( 3 ) ) 




WRITE 


( 3 ),SF,MF=E 




CHECK 


(2) 




CHECK 


(3) 




B 


READRECD 


FINISH 


CLOSE 


( UPDATDCB ) 



Call routine to update R2 
Check read for next record 
Write updated R2 



R3 



If R3 requires no update, check 

write for R2 and loop 

Call routine to update R3 

Write updated R3 

Check write for R2 

Check write for R3 

Loop 

End-of-Data exit routine 



Figure 50. Updating a Member of a Partitioned Data Set 
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been allocated, the data set must be reorganized by the IEBCOPY utility program. 

When you rewrite the member, you must provide two DCBs, one for input and one for 
output. Both DCB macro instructions can refer to the same data set, that is, only one DD 
statement is required. 

You can reflect the change in location of the member either automatically, by indicating 
a disposition of OLD, or by using the STOW macro instruction. Although the old 
member is, in effect, deleted, its space cannot be reused until the data set is reorganized. 

If an out-of-space condition occurs when updating a PDS member, the error recovery 
procedure will STOW the PDS member as 'TEMPNAME'. The original member will 
remain intact. 



Processing a Partitioned Data Set Residing on MSS 



If OPTCD=H is specified in the DCB subparameter of a DD statement, it specifies that, 
if a Partitioned Data set is being opened for input and resides on an MSS device, then at 
OPEN time the data set is staged to EOF on the virtual DASD device. If the option is 
not specified, only the directory is staged at OPEN time and cylinder faults occur during 
processing. This option might be used with the IEBCOPY utility program opening the 
PDS to reorganize and compress the data space. This BPAM option, OPTCD=H, may 
only be coded on the DD statement. 



Processing an Indexed Sequential Data Set 



The organization of an indexed sequential data set allows you a great deal of flexibility in 
the operations you can perform. The data set can be read or written sequentially, 
individual records can be processed in any order, records can be deleted, and new 
records can be added. The system automatically locates the proper position in the data 
set for new records and makes any necessary adjustments when records are deleted. 

The queued access technique must be used to create an indexed sequential data set. It 
can also be used to sequentially process or update the data set and to add records to the 
end of the data set. The basic access technique can be used to insert new records 
between records already in the data set and to update the data set directly. 



Indexed Sequential Data Set Organization 



The records in an indexed sequential data set are arranged according to collating 
sequence by a key field in each record. Each block of records is preceded by a key field 
that corresponds to the key of the last record in the block. 

An indexed sequential data set resides on direct-access storage devices and can occupy 
up to three different areas: 

• Prime Area — This area, also called the prime data area, contains data records and 
related track indexes. It exists for all indexed sequential data sets. 

• Overflow Area — This area contains records that overflow from the prime area when 
new data records are added. It is optional. 

• Index Area — This area contains master and cylinder indexes associated with the data 
set. It exists for a data set that has a prime area occupying more than one cylinder. 

The indexes of an indexed sequential data set are analogous to the card catalog in a 
library. For example, if the library user knows the name of the book or the author, he 
can look in the card catalog and obtain a catalog number that will enable him to locate 
the book in the book files. He would then go to the shelves and proceed through rows 
until he found the shelf containing the book. Usually each row contains a sign to indicate 
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Prime Area 



the beginning and ending numbers of all books in that particular row. Thus, as he 
proceeded through the rows, he would compare the catalog number obtained from the 
index with the numbers posted on each row. Upon locating the proper row, he would 
then search that row for the shelf that contained the book. Then he would look at the 
individual book numbers on that shelf until he found the particular book. 

ISAM uses the indexes in much the same way to locate records in an indexed sequential 
data set. 

As the records are written in the prime area of the data set, the system accounts for the 
records contained on each track in a track index area. Each entry in the track index 
identifies the key of the last record on each track. There is a track index for each cylinder 
in the data set. If more than one cylinder is used, the system develops a higher-level 
index called a cylinder index. Each entry in the cylinder index identifies the key of the 
last record in the cylinder. To increase the speed of searching the cylinder index, you can 
request that a master index be developed for a specified number of cylinders, as shown 
in Figure 51. 

Rather than reorganize the whole data set when records are added, you can request that 
space be allocated for additional records in an overflow area. 



Records are written in the prime area when the data set is created or updated. The last 
track of prime data is reserved for an end-of-file mark. The portion of Figure 51 labeled 
Cylinder 1 illustrates the initial structure of the prime area. Although the prime area can 
extend across several noncontiguous areas of the volume, all the records are written in 
key sequence. Each record must contain a key; the system automatically writes the key 
of the highest record before each block. 
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Figure 51. Indexed Sequential Data Set Organization 
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When the ABSTR option of the SPACE parameter of the DD statement is used to 
generate a multivolume prime area, the VTOC of the second volume and on all 
succeeding volumes must be contained within cylinder of the volume. 



The operating system generates track and cylinder indexes automatically. Up to three 
levels of master indexes are created if requested. 

Track Index: This is the lowest level of index and is always present. There is one track 
index for each cylinder in the prime area; it is written on the first track(s) of the cylinder 
that it indexes. 
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The index consists of a series of paired entries, that is, of a normal entry and an overflow 
entry for each prime track. For fixed-length records, each normal entry (and also 
DCBFIRSH) points to either record or the first prime record on a shared track. For 
variable-length records, the normal entry contains the key of the highest record on the 
track and the address of the last record on the track. The overflow entry is originally the 
same as the normal entry. (This is why 100 appears twice on the track index for 
cylinder 1 in Figure 51.) The overflow entry is changed when records are added to the 
data set. Then the overflow entry contains the key of the highest overflow record and the 
address of the lowest overflow record logically associated with the track. Figure 52 
shows the format of a track index. 

If all the tracks allocated for the prime data area are not used, the index entries for the 
unused ones are flagged as inactive. The last entry of each track index is a dummy entry 
indicating the end of the index. When fixed-length record format has been specified, the 
remainder of the last track of each cylinder used for a track index contains prime data 
records if there is room for them. 

Each index entry has the same format. It is an unblocked, fixed-length record consisting 
of a count, a key, and a data area. The length of the key corresponds to the length of the 
key area in the record to which it points. The data area is always 10 bytes long. It 
contains the full address of the track or record to which the index points, as well as the 
level of the index and the entry type. 

Cylinder Index: For every track index created, the system generates a cylinder index 
entry. There is one cylinder index for a data set, each entry of which points to a track 
index. Since there is one track index per cylinder, there is one cylinder index entry for 
each cylinder in the prime data area, except in the case of a 1 -cylinder prime area. As 
with track indexes, inactive entries are created for any unused cylinders in the prime data 
area. 

Master Index: As an optional feature, the operating system creates, at your request, a 
master index. The presence of this index makes long, serial searches through a large, 
cylinder index unnecessary. 
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Normal key = key of the highest record on the prime data track 

^Normal data = address of the prime data track 

Overflow key = key of the highest overflow record logically associated with the prime data track 

Overflow data = address of the lowest overflow record logically associated with the prime data track 

Notes: 

• If there are no overflow records, overflow key and data entries are the same as normal key and data entries. 

• This figure is a logical representation only; that is, it makes no attempt to show the physical size of track index entries. 

Figure 52. Format of Track Index Entries 
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Overflow Areas 



You can specify the conditions under which you want a master index created. For 
example, if you have specified NTM=3 and OPTCD=M in your DCB macro instruction, 
a master index is created when the cylinder index exceeds 3 tracks. The master index 
consists of one entry for each track of cylinder index. If your data set is extremely large, 
a higher-level master index is created when the first-level master index exceeds three 
tracks. This higher-level master index consists of one entry for each track of the 
first-level master index. This procedure can be repeated for as many as three levels of 
master index. 



As records are added to an indexed sequential data set, space is required to contain those 
records that will not fit on the prime data track on which they belong. You can request 
that a number of tracks be set aside as a cylinder overflow area to contain overflows 
from prime tracks in each cylinder. An advantage of using cylinder overflow areas is a 
reduction of search time required to locate overflow records. A disadvantage is that there 
will be unused space if the additions are unevenly distributed throughout the data set. 

Instead of, or in addition to, cylinder overflow areas, you can request an independent 
overflow area. Overflow from anywhere in the prime data area is placed in a specified 
number of cylinders reserved solely for overflow records. An advantage of having an 
independent overflow area is a reduction in unused space reserved for overflow. A 
disadvantage is the increased search time required to locate overflow records in an 
independent area. 

If you request both cylinder overflow and independent overflow, the cylinder overflow 
area is used first. It is a good practice to request cylinder overflow areas large enough to 
contain a reasonable number of additional records and an independent overflow area to 
be used as the cylinder overflow areas are filled. 

Adding Records to an Indexed Sequential Data Set 

Either the queued access technique or the basic access technique may be used to add 
records to an indexed sequential data set. A record to be inserted between records 
already in the data set must be inserted by the basic access method using WRITE KN 
(key new). Records added to the end of a data set, that is, records with successively 
higher keys, may be added to the prime data area or the overflow area by the basic 
access method using WRITE KN, or they may be added to the prime data area by the 
queued access technique using the PUT macro instruction. 

Inserting New Records into an Existing Indexed Sequential Data Set 

As you add records to an indexed sequential data set, the system inserts each record in its 
proper sequence according to the record key. The remaining records on the track are 
then moved up one position each. If the last record does not fit on the track, it is written 
in the first available location in the overflow area. A 10-byte link field is added to the 
record put in the overflow area to connect it logically to the correct track. The proper 
adjustments are made to the track index entries. This procedure is illustrated in 
Figure 53. 

Subsequent additions are written either on the prime track or as part of the overflow 
chain from that track. If the addition belongs after the last prime record on a track but 
before a previous overflow record from that track, it is written in the first available 
location in the overflow area. Its link field contains the address of the next record in the 
chain. 
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Adding New Records to the End of an Indexed Sequential Data Set 

Records added to the end of a data set, that is, records with successively higher keys, 
may be added by the basic access method using WRITE KN (key new), or by the queued 
access method using the PUT macro instruction (resume load). In either case records 
may be added to the prime data area. 

When you use the WRITE KN macro instruction, the record being added is placed in the 
prime data area only if there is room for it on the prime data track containing the record 
with the highest key currently in the data set. If there is not sufficient room on that track, 
the record is placed in the overflow area and linked to that prime track even though 
additional prime data tracks originally allocated have not been filled. 

When you use the PUT macro instruction (resume load), records are added to the prime 
data area until the space originally allocated is filled. Once this allocated prime area is 
filled, you can add records to the data set using WRITE KN, in which case they will be 
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placed in the overflow area. Resume load is discussed in more detail later under 
"Creating an Indexed Sequential Data Set." 

In order to add records with successively higher keys using the PUT macro instruction 
(resume load): 

• The key of any record to be added must be higher than the highest key currently in 
the data set. 

• The DD statement must specify DISP=MOD (or, for VS2.03.808, the EXTEND 
option is specified in the OPEN macro). 

• The data set must have been successfully closed when it was created or when records 
were previously added using the PUT macro instruction. 

You may continue to add fixed-length records in this manner until the original space 
allocated for prime data is exhausted. 

When you add records to an indexed sequential data set using the PUT macro instruction 
(resume load), new entries are also made in the indexes. During resume load on a data 
set with a partially filled track and/or a partially filled cylinder, the track index entry 
and/or the cylinder index entry is overlaid when the track or cylinder is filled. If resume 
load abnormally terminates after these index entries have been overlaid, a subsequent 
resume load will get a sequence check when adding a key that is higher than the highest 
key at the last successful CLOSE but lower than the key in the overlaid index entry. 
When the SYNAD exit is taken for a sequence check, register contains the address of 
the highest key of the data set. 

Maintaining an Indexed Sequential Data Set 

An indexed sequential data set must be reorganized occasionally for two reasons: 

• The overflow area will eventually be filled. 

• Additions increase the time required to locate records directly. 

The frequency'of reorganization depends on the activity of the data set and on your 
timing and storage requirements. There are two ways you can accomplish reorganization: 

• You can reorganize the data set in two passes by writing it sequentially into another 
area of direct-access storage or magnetic tape and then recreating it in the original 
area. 

• You can reorganize the data set in one pass by writing it directly into another area of 
direct-access storage. In this case, the area occupied by the original data set cannot be 
used by the reorganized data set. 

The operating system maintains statistics that are pertinent to reorganization. The 
statistics, written on the direct-access volume and available in the DCB for checking, 
include the number of cylinder overflow areas, the number of unused tracks in the 
independent overflow area, and the number of references to overflow records other than 
the first. They appear in the RORG1, RORG2, and RORG3 fields of the DCB. 

If you indicate when creating or updating the data set that you want to be able to flag 
records for deletion during updating, you can set the delete code (the first byte of a 
fixed-length record or the fifth byte of a variable-length record) to X'FF'. If a flagged 
record is forced off its prime track during a subsequent update, it will not be rewritten in 
the overflow area, as shown in Figure 54, unless it has the highest key on that cylinder. 
Similarly, when you process sequentially, flagged records are not retrieved for processing. 
During direct processing, flagged records are retrieved like any other records, and you 
should check them for the delete code. 
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Note that a WRITE KN (key new) to a data set containing variable-length records 
removes all of the deleted records from that prime data track. 

Note that to use the delete option, RKP must be greater than for fixed-length records 
and greater than 4 for variable-length records. 
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Figure 54. Deleting Records From an Indexed Sequential Data Set 
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Indexed Sequential Buffer and Work Area Requirements 

The only case in which you will ever have to compute the buffer length (BUFL) 
requirements for your program is when you use the BUILD or GETPOOL macro 
instruction to construct the buffer area. If you are creating an indexed sequential data set 
(using the PUT macro instruction), each buffer must be 8 bytes longer than the blocksize 
to allow for the hardware count field, that is: 



Buffer length = 8 + Blocksize 




Buffer 



One exception to this formula arises when you are dealing with an unblocked format-F 
record whose key field precedes the data field; its relative key position is (RKP=0). In 
that case the key length must also be added, that is: 

Buffer length = 8 + Key length + Record length 
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The buffer requirements for using the queued access technique to read or update (using 
the GET or PUTX macro instruction) an indexed sequential data set are discussed 
below. 

For fixed-length unblocked records when both the key and data are to be read and for 
variable-length unblocked records, padding is added so that the data will be on a 
doubleword boundary, that is: 



Buffer length = Key length + Padding + 10 + Blocksize 
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For fixed-length unblocked records when only data is to be read: 
Buffer length = 16 + LRECL 
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For fixed-length blocked records: 
Buffer length = 16 + Blocksize 
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For variable-length blocked records, padding is 2 if the buffer starts on a fullword 
boundary that is not also a doubleword boundary or 6 if the buffer starts on a 
doubleword boundary, that is: 



Buffer length = 12 or 16 + Blocksize 




If you are using the input data set with fixed-length, unblocked records as a basis for 
creating a new data set, a work area is required. 

The size of the work area is given by: 
Work area = Key length + Record length 




-Work Area- 



If you are reading only the data portion of fixed-length unblocked records or 
variable-length records, the work area is the same size as the record, that is: 

Work area = Record length 
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When you use the basic access technique to update records in an indexed sequential data 
set, the key length field need not be considered in determining your buffer requirements. 
The area for fixed-length records must be: 
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For variable-length records, padding is 2 if the buffer starts on a fullword boundary that 
is not also a doubleword boundary or 6 if a buffer starts on a doubleword boundary. 
Thus, the area must be: 

Buffer length = 12 or 16 + Blocksize 
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You can speed up the process of adding fixed-length or variable-length records to a data 
set by using the MSWA parameter of the DCB macro instruction to provide a special 
work area for the operating system. The size of the work area (SMSW parameter in the 
DCB) must be large enough to contain a full track of data, the count fields of each block, 
and the work space for inserting the new record. 

The size of the work area needed varies according to the record format and the device 
type. You can calculate it during execution using device-dependent information obtained 
with the DEVTYPE macro instruction and data set information from the DSCB obtained 
with the OBTAIN macro instruction. The DEVTYPE and OBTAIN macro instructions 
are discussed in OS/VS2 System Programming Library: Data Management. 

Note that you can use the DEVTYPE macro instruction only if the index and prime areas 
are on devices of the same type or if the index area is on a device with a larger track 
capacity than that of the device containing the prime area. If you are not trying to 
maintain device independence, you may precalculate the size of the work area needed 
and specify it in the SMSW field of the DCB macro instruction. The maximum value for 
SMSW is 65,535. 

For calculating the size of the work area, refer to the storage device capacities shown in 
Figure 62 under "Estimating Space Requirements" and the device overhead formulas 
given in the same section. 

For fixed-length blocked records, SMSW is calculated as follows: 

SMSW = HIRPD(BLKSIZE + 8) + LRECL + KEYLEN 

The formula for fixed-length unblocked records is 

SMSW = HIRPD(KEYLEN + LRECL + 8) + 2 

The value for HIRPD is in the index (format-2) DSCB. OS/VS2 System Programming 
Library: Debugging Handkook shows the exact location of this field in the index DSCB. 
If you don't use the MSWA and SMSW parameters, the control program supplies a work 
area using the formula BLKSIZE + LRECL + KEYLEN. 

For variable-length records, SMSW may be calculated by one of two methods. The first 
method may lead to faster processing although it may require more storage than the 
second method. 

The first method is as follows: 

SMSW = HIRPD(BLKSIZE + 8) + LRECL + KEYLEN + 10 

The second method is as follows: 

SMSW=/ Track Capacity-Bin- l\ (BLKSIZE)+8(HIRPD)+LRECL+KEYLEN+ 10+(REM-N-KEYLEN) 

In all of the above formulas, the terms BLKSIZE, LRECL, KEYLEN, and SMSW are 
the same as the parameters in the DCB macro instruction. REM is the remainder of the 
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division operation in the formula and N is the first constant in the Bi formulas described 
in Figure 63. (REM-N-KEYLEN) is added only if it is positive. The second method 
yields a minimum value for SMSW. Therefore, the first method is valid only if its 
application results in a value higher than the value that would be derived from the second 
method. If neither MSWA nor SMSW is specified, the control program supplies the work 
area for variable-length records, using the second method to calculate the size. 

Another technique to increase the speed of processing is to provide space in virtual 
storage for the highest-level index. To specify the address of this area, use the MSHI 
operand of the DCB. When the address of this area is specified, you must also specify its 
size, which you can do by using the SMSI operand of the DCB. The maximum value for 
SMSI is 65,535. If you do not use this technique, the index on the volume must be 
searched. If the high-level index is greater than 65,535 bytes in length, your request for 
the high-level index in storage is ignored. 

The size of the storage area (SMSI parameter) varies. To allocate that space during 
execution, you can find the size of the high-level index in the DCBNCRHI field of the 
DCB during your DCB exit routine or after the data set is open. Use the DCBD macro 
instruction to gain access to the DCBNCRHI field (see "Modifying the Data Control 
Block" in Part 1). You can also find the size of the high-level index in the DS2NOBYT 
field of the index (format 2) DSCB, but you must use the utility program IEHLIST to 
print the information in the DSCB. You can calculate the size of the storage area 
required for the high-level index by using the formula 

SMSI = /Number of Tracks \ /Number of EntriesX (Key Length + 10) 

\in High-Level Index/ \per Track J 

The formula for calculating the number of tracks in the high-level index is in the section 
"Calculating Space Requirements for an Indexed Sequential Data Set" in Part 3. When a 
data set is shared and has the DCB integrity feature (DISP=SHR), the high-level index 
in storage is not updated when DCB fields are changed. 



Controlling an Indexed Sequential Data Set Device 



An indexed sequential data set is processed sequentially or directly. Direct processing is 
accomplished by the basic access technique. Because you provide the key for the record 
you want read or written, all device control is handled automatically by the system. If 
you are processing the data set sequentially, using the queued access technique, the 
device is automatically positioned at the beginning of the data set. 

In some cases, you may wish to process only a section or several separate sections of the 
data set. You do this by using the SETL macro instruction, which directs the system to 
begin sequential retrieval at the record having a specific key. The processing of 
succeeding records is the same as for normal sequential processing, except that you must 
recognize when the last desired record has been processed. At this point, issue the 
ESETL macro instruction to terminate sequential processing. You can then begin 
processing at another point in the data set. 



SETL — Specify Start of Sequential Retrieval 



The SETL macro instruction enables you to retrieve records starting at the beginning of 
an indexed sequential data set or at any point in the data set. Processing that is to start at 
a point other than the beginning can be requested in the form of a record key, a key class 
(key prefix), or an actual address of a prime data record. 

The key class concept is useful because you do not have to know the whole key of the 
first record to be processed. A key class comprises all of the keys that begin with 
identical characters. The key class is defined by specifying the desired characters of the 
key class at the address specified in the lower-limit operand of the SETL macro and 
setting the remaining characters to the right of the key class to binary zeros. 
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To use actual addresses, you must keep an account of where the records were written 
when the data set was created. The device address of the block containing the record just 
processed by a PUT-move macro instruction is available in the 8-byte data control block 
field DCBLPDA. For blocked records the address is the same for each record in the 
block. 

Normally, when a data set is created with the delete option specified, deleted records 
cannot be retrieved using the QISAM retrieval mode. When the delete option is not 
specified in the DCB, the SETL macro options function as follows: 

SETL B — Start at first record in the data set 

SETL K — Start with record having the specified key 

SETL KH — Start with record whose key is equal to or higher than the specified key 

SETL KC — Start with first record having a key that falls into the specified key class 

SETL I — Start with the record found at the specified direct-access address in the 
prime area of the data set 

Because the DCBOPTCD field in the DCB can be changed after the data set is created 
(by respecifying the OPTCD in the DCB or DD card), it is possible to retrieve deleted 
records. In this case, SETL functions as noted above. 

When the delete option is specified in the DCB, the SETL macro options function as 
follows: 

SETL B — Start retrieval at first nondeleted record in the data set 

SETL K — Start retrieval at record matching the specified key if that record is not 

deleted. If the record is deleted, an NRF (no record found) indication is set 
in the DCBEXCD field of the DCB, and SYNAD is given control 

SETL KH — Start with first nondeleted record whose key is equal to or higher than the 
specified key 

SETL KC — Start with first nondeleted record having a key that falls into the specified 
key class or follows the specified key class 

SETL I — Start with first nondeleted record following the specified direct-access 
address 

With the delete option not specified, QISAM retrieves and handles records marked for 
deletion like nondeleted records. 

Note: Regardless of the SETL or delete option specified, the NRF condition will be 
posted in the DCBEXCD field of the DCB, and SYNAD is given control if the key or 
key class: 

• Is higher than any key or key class in the data set 

• Does not have a matching key or key class in the data set 

ESETL— End Sequential Retrieval 

The ESETL macro instruction directs the system to stop retrieving records from an 
indexed sequential data set. A new scan limit can then be set, or processing terminated. 
An end-of -data-set indication automatically terminates retrieval. An ESETL macro 
instruction must be executed before another SETL macro instruction (described above) 
using the same DCB is executed. 

Note: An ESETL macro instruction should be executed before another SETL macro 
instruction if the previous SETL macro instruction completed with an error. 
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Creating an Indexed Sequential Data Set 



You can create an indexed sequential data set in one step or in several steps. You can 
create the data set either by writing all records in a single step or by writing one group of 
records in one step and writing additional groups of records in subsequent steps. Writing 
records in subsequent steps is resume loading. When using either one step or several 
steps, you must present the records for writing in ascending order by key. 

To create an indexed sequential data set by the one-step method, you should proceed as 
follows: 

. Code DSORG=IS or DSORG=ISU and MACRF=PM or MACRF=PL in the DCB 
macro instruction. 

• Specify in the DD statement the DCB attributes DSORG=IS or DSORG=ISU, record 
length (LRECL), blocksize (BLKSIZE), record format (RECFM), key length 
(KEYLEN), relative key position (RKP), options required (OPTCD), cylinder 
overflow (CYLOFL), and the number of tracks for a master index (NTM). Specify 
space requirements with the SPACE parameter. To reuse previously allocated space, 
omit the SPACE parameter and code DISP=(OLD, KEEP). 

• Open the data set for output. 

• Use the PUT macro instruction to place all the records or blocks on the direct-access 
volume. 

• Close the data set. 

The records that compose a newly created data set must be presented for writing in 
ascending order by key. You can merge two or more input data sets. If you want a data 
set with no records (a null data set), you must write at least one record when you create 
the data set. You can subsequently delete this record to achieve the null data set. 

If the records are blocked, you should not write a record with a hexadecimal value of FF 
and a key of hexadecimal value FF. This value is used for padding. If it occurs as the 
last record of a block, the record cannot be retrieved. If the record is moved to the 
overflow area, it is lost. 

When creating an indexed sequential data set, a procedure called loading, you can 
improve performance by using the full-track-index-write option. You do this by 
specifying OPTCD=U in the DCB. This causes the operating system to accumulate 
track-index entries in virtual storage. Note that the full-track-index-write option can be 
used only for fixed-length records. 

If you do not specify this option, the operating system writes each normal-overflow pair 
of entries for the track index after the associated prime data track has been written. If 
you specify this option, the operating system accumulates track-index entries in virtual 
storage until either there are enough entries to fill a track or end-of-data or 
end-of-cylinder is reached. Then the operating system writes these entries as a group, 
writing one group for each track of track index. This option requires allocation of more 
storage space (the space in which the track-index entries are gathered), but the number 
of I/O operations required to write the index can be significantly decreased. 

When you specify the full-track-index-write option, the track index entries are written as 
fixed-length unblocked records. If a large enough area of virtual storage is not available, 
the entries are written as they are created, that is, in normal-overflow pairs. 

Once an indexed sequential data set has been created, its characteristics cannot be 
changed. However, for added flexibility, the system allows you to retrieve records using 
either the queued access technique with simple buffering, or the basic access technique 
with dynamic buffering. 
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Tape-to-Disk — Indexed Sequential Data Set: The example in Figure 55 shows the 
creation of an indexed sequential data set from an input tape containing 60-character 
records. The key by which the data set is organized is in positions 20-29. The output 
records will be an exact image of the input, except that the records will be blocked. One 
track per cylinder is to be reserved for cylinder overflow. Master indexes are to be built 
when the cylinder index exceeds six tracks. Reorganization information about the status 
of the cylinder overflow areas is to be maintained by the system. The delete option will 
be used during any future updating. 

To create an indexed sequential data set in more than one step, create the first group of 
records using the one step method described above. This first section must contain at 
least one data record. The remaining records can then be added to the end of the data set 
in subsequent steps using resume load. Each group to be added must contain records 
with successively higher keys. This method allows you to create the indexed sequential 
data set in several short time periods rather than in a single long one. 

This method also allows you to provide limited recovery from uncorrectable output 
errors. When an uncorrectable output error is detected, do not attempt to continue 
processing or to close the data set. If you have provided a SYNAD routine, it should 
issue the ABEND macro instruction to terminate processing. If no SYNAD routine is 
provided, the control program will terminate your processing. If the error shows that 
space in which to add the record was not found, you must close the data set; issuing 
subsequent PUT macro instructions can cause unpredictable results. You should begin 
recovery at the record following the end of the data as of the last successful close. The 
rerun time is limited to that necessary to add the new records, rather than to that 
necessary to recreate the whole data set. 

When you extend an indexed sequential data set with resume load, the disposition 
parameter of the DD statement must specify MOD. To ensure that the necessary control 
information is in the DSCB before attempting to add records, you should at least open 
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Figure 55. Creating an Indexed Sequential Data Set 
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and close the data set successfully on a version of the system that includes resume load. 
This need be done only if the data set was created on a previous version of the system. 
Records may be added to the data set by resume load until the space allocated for prime 
data in the first step has been filled. 

During resume load on a data set with a partially filled track and/or a partially filled 
cylinder, the track index entry and/or the cylinder index entry is overlaid when the track 
or cylinder is filled. Resume load for variable-length records begins at the next sequential 
track of the prime data set. If resume load abnormally terminates after these index 
entries have been overlaid, a subsequent resume load will result in a sequence check 
when it adds a key that is higher than the highest at the last successful CLOSE but lower 
than the key in the overlaid index entry. When the SYNAD exit is taken for a sequence 
check, register contains the address of the high key of the data set. However, if the 
SYNAD exit is taken during CLOSE, register will contain the IOB address. 

Retrieving and Updating an Indexed Sequential Data Set 

Sequential Retrieval and Update 

To sequentially retrieve and update records in an indexed sequential data set: 

• Code DSORG=IS or DSORG=ISU to agree with what you specified when you 
created the data set, and MACRF=GL, MACRF=SK, or MACRF=PU in the DCB 
macro instruction. 

• Code a DD statement for retrieving the data set. The data set characteristics and 
options are as defined when the data set was created. 

• Open the data set. 

• Set the beginning of sequential retrieval (SETL). 

• Retrieve records and process as required, marking records for deletion as required. 

• Return records to the data set. 

• Use ESETL to end sequential retrieval as required and reset the starting point. 

• Close the data set to end all retrieval. 

Sequential Updates — Indexed Sequential Data Set: Assume that, using the data set 
created in the previous example, you are to retrieve all records beginning with 915. 
Those records with a date (positions 13-16) before today's date are to be deleted. The 
date is in the standard form as returned by the system in response to the TIME macro 
instruction, that is, packed decimal OOyyddds. Overflow records can be logically deleted 
even though they cannot be physically deleted from the data set. 

One way to solve this problem is shown in Figure 56. 

Direct Retrieval and Update 

By using the basic indexed sequential access method (BISAM) to process an indexed 
sequential data set, you can make direct references to the records in the data set for the 
purpose of: 

• Direct retrieval of a record by its key 

• Direct update of a record 

• Direct insertion of new records 

Because the operations are direct, there can be no anticipatory buffering. However, the 
system provides dynamic buffering each time a read request is made, if specified. 
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//INDEXDD DD 
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LIMIT 


DC 


C'916' 




DC 


XL7 ' ' 



Set scan limit 
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Locate mode 



Compare for old date 

Flag old record for deletion 
Return delete record 



Key prefix 
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CHECKERR 

Test DCBEXCD1 and DCBEXDE2 for error indication 

Error Routines 

ENDJOB CLOSE (ISDATA) 

ISDATA DCB DDNAME=INDEXDD,DSORG=IS ,MACRF=( GL, SK, PU ) , C 

SYNAD=CHECKRR 
Figure 56. Sequentially Updating an Indexed Sequential Data Set 

To ensure that the requested record is in virtual storage before you start processing, you 
must issue a WAIT or CHECK macro instruction. If you issue a WAIT macro 
instruction, you must test the exception code field of the DECB. If you issue a CHECK 
macro instruction, the system tests the exception code field in the DECB. If an error 
analysis routine has not been specified and a CHECK is issued, the program is 
abnormally terminated with a system completion code X'001'. In either case, if you wish 
to determine whether the record is an overflow record, you should test the exception 
code field of the DECB. 

After you test the exception code field of the DECB, you need not set it to 0. If you have 
used a READ KU macro instruction and if you plan to use the same DECB again to 
rewrite the updated record using a WRITE K macro instruction, you should not set the 
field to 0. If you do, your record may not be rewritten properly. 

To update existing records, you must use the READ KU and WRITE K combination. 
Because READ KU implies that the record will be rewritten in the data set, the system 
retains the DECB and the buffer used in the READ KU and uses them when the record 
is written. If you decide not to write the record, you should use the same DECB in 
another read or write macro instruction or issue a FREEDBUF macro instruction if 
dynamic buffering was used. If you issue several READ KU or WRITE K macro 
instructions before checking the first one, you may destroy some of your updated records 
unless the records are from different blocks. 

If there is the possibility that your task and another task will be simultaneously accessing 
the same data set, or the same task has two or more DCBs opened for the same data set, 
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you should use the DCB integrity feature. You specify the DCB integrity feature by 
coding DISP=SHR in your DD statement. In this way you ensure that the DCB fields are 
maintained for your program to process the data set correctly. If you do not use 
DISP=SHR and more than one DCB is open for updating the data set, the results are 
unpredicatable. 

If you specify DISP=SHR, you must also issue an ENQ for the data set before each 
input/output request and a DEQ upon completion of the request. All users of the data 
set must use the same qname and rname operands for ENQ. For example, the users 
might use the data set name as the qname operand. For more information about using 
ENQ and DEQ, see OS/VS2 Supervisor Services and Macro Instructions. 

When you are using scan mode with QISAM and you want to issue PUTX, issue an ENQ 
on the data set before processing it and a DEQ after processing is complete. ENQ must 
be issued before the SETL macro instruction, and DEQ must be issued after the ESETL 
macro instruction. When you are using BISAM to update the data set, do not modify any 
DCB fields or issue a DEQ until you have issued CHECK or WAIT. 

Sharing a BISAM DCB between Related Tasks: When a task using BISAM processes a 
data set whose DCB is defined and opened by a related task, the task must issue an ENQ 
on the DCB before an input/output request is issued and must issue a DEQ after the 
WAIT or CHECK for the input/output request is issued. If the task does not enqueue 
the DCB and any of its related tasks terminates abnormally, the task may enter a wait 
state or a program check may occur. See OS/VS2 Supervisor Services and Macro 
Instructions for more information on the ENQ and DEQ macro instructions and on 
multitasking. 

For subtasking, I/O requests should be issued by the task which owns the DCB or a task 
which will remain active as long as the DCB is open. If the taks that issued the I/O request 
terminates, the storage used by its data areas (such as IOBs) may be freed or queuing switches 
in the DCB work area may be left set on, causing another task issuing an I/O request to the 
DCB to program check or to enter the wait state. For example, if a subtask issues and 
completes a READ KU I/O request, the IOB which was created by the subtask is attached 
to the DCB update queue. If that subtask terminates, and subpool zero is not shared with 
the subtask owning the DCB, the IOB storage area is freed and the integrity of the ISAM 
update queue is destroyed. A request from another subtask, attempting to use that queue, 
may cause unpredictable abends. As another example, if a WRITE KEY NEW is in process 
when the subtask terminates, the "WRITE-KEY-NEW-IN-PROCESS" bit is left set on. If 
another I/O request is issued to the DCB, the request is queued but cannot proceed. 

Direct Update With Exclusive Control — Indexed Sequential Data Set: In the example 
shown in Figure 57, the previously described data set is to be updated directly with 
transaction records on tape. The input tape records are 30 characters long, the key is in 
positions 1-10, and the update information is in positions 11-30. The update information 
replaces data in positions 31-50 of the indexed sequential data record. 

Exclusive control of the data set is requested since more than one task may be referring 
to the data set at the same time. Notice that exclusive control is released after each block 
is written to avoid tying up the data set until the update is completed. 

Note the use of the FREEDBUF macro instruction in Figure 57. Usually the 
FREEDBUF macro instruction has two functions: 

• To indicate to the ISAM routines that a record that has been read for update will not 
be written back 

• To free a dynamically obtained buffer 

In Figure 57, since the read operation was unsuccessful, the FREEDBUF macro 
instruction frees only the dynamically obtained buffer. 
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//INDEXDD DD 
//TAPEDD DD 
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Figure 57. Directly Updating an Indexed Sequential Data Set 



The first function of FREEDBUF allows you to read a record for update and then decide 
not to update it without performing a WRITE for update. You can use this function even 
when your READ macro instruction does not specify dynamic buffering, provided that 
you have included S (for dynamic buffering) in the MACRF field of your READ DCB. 

You can effect an automatic FREEDBUF simply by reusing the DECB, that is, by 
issuing another READ or a WRITE KN to the same DECB. You should use this feature 
whenever possible, since it is more efficient than FREEDBUF. For example, in 
Figure 57, the FREEDBUF macro instruction could be eliminated, since the WRITE KN 
addressed the same DECB as the READ KU. 
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For an indexed sequential data set with variable-length records, you may make three 
types of updates by using the basic access technique. You may read a record and write it 
back with no change in its length, simply updating some part of the record. You do this 
with a READ KU followed by a WRITE K, the same way you update fixed-length 
records. Two other methods for updating variable-length records use the WRITE KN 
macro instruction and allow you to change the record length. 

In one method, a record read for update (by a READ KU) may be updated in a manner 
that will change the record length and then be written back with its new length by a 
WRITE KN. In the second method, you may replace a record with another record having 
the same key and possibly a different length using the WRITE KN macro instruction. To 
replace a record, it is not necessary to have first read the record. 

In either method, when changing the record length, you must place the new length in the 
DECBLGTH field of the DECB before issuing the WRITE KN macro instruction. If you 
use a WRITE KN macro instruction to update a variable-length record that has been 
marked for deletion, the first bit (no record found) of the exceptional condition code 
field (DECBEXC1) of the DECB is set on. If this condition is found, the record must be 
written using a WRITE KN with nothing specified in the DECBLGTH field. 



Part 2: Data Management Processing Procedures 124.1 



Do not try to use the DECBLGTH field to determine the length of a record read, 
because DECBLGTH is for use with writing records, not reading them. If you are 
reading fixed-length records, the length of the record read is in DCBLRECL, and if you 
are reading variable-length records, the length is in the record descriptor word (RDW). 

Direct Update — Indexed Sequential Data Set with Variable-Length Records: In Figure 58, 
an indexed sequential data set with variable-length records is updated directly with 
transaction records on tape. The transaction records are of variable length and each 
contains a code identifying the type of transaction. Transaction code 1 indicates that an 
existing record is to be replaced by one with the same key; 2 indicates that the record is 
to be updated by appending additional information, thus changing the record length; 3 or 
greater indicates that the record is to be updated with no change to its length. For this 
example, the maximum record length of both data sets is 256 bytes. The key is in 
positions 6-15 of the records in both data sets. The transaction code is in position 5 of 
records on the transaction tape. The work area (REPLAREA) size is equal to the 
maximum record length plus 16 bytes. 
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//INDEXDD DD 
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Figure 58. Directly Updating an Indexed Sequential Data Set with Variable-Length Records 
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Processing a Direct Data Set 



In a direct data set, there is a relationship between a control number or identification of 
each record and its location on the direct-access volume. This relationship allows you to 
gain access to a record without an index search. You determine the actual organization of 
the data set. If the data set has been carefully organized, location of a particular record 
takes less time than with an indexed sequential data set. 

The DSORG parameter of the DCB macro specifies the type of processing to be 
performed, while DSORG in the DD statement specifies the organization of the data set. 

Although you can process a direct data set sequentially using either the queued access 
technique or the basic access technique, you cannot read record keys using the queued 
access technique. When you use the basic access technique, each unit of data transmitted 
between virtual storage and an I/O device is regarded by the system as a record. If, in 
fact, it is a block, you must perform any blocking or deblocking required. For that 
reason, the LRECL field is not used when processing a direct data set. Only BLKSIZE 
must be specified when you add or update records on a direct data set. 

If dynamic buffering is specified for your direct data set, the system will provide a buffer 
for your records. If dynamic buffering is not specified, you must provide a buffer for the 
system to use. 

As indicated in the discussion of direct-access devices, record keys are optional. If they 
are specified, they must be used for every record and must be of a fixed length. 



Organizing a Direct Data Set 



In developing the organization of your data set, you can use direct addressing. When 
direct addresses are used, the location of each record in the data set is known. 

If format-F records with keys are being written, the key of each record can be used to 
identify the record. For example, a data set with keys ranging from to 4999 should be 
allocated space for 5000 records. Each key relates directly to a location that you can 
refer to as a relative record number. Therefore, each record should be assigned a unique 
key. If identical keys are used it is possible, during periods of high CPU and channel 
activity, to skip the desired record and retrieve the next record on the track. The main 
disadvantage of this type of organization is that records may not exist for many of the 
keys even though space has been reserved for them. 

Space could be allocated on the basis of the number of records in the data set rather than 
on the range of keys. This type of organization requires the use of a cross-reference 
table. When a record is written in the data set, you must note the physical location either 
as an actual address or as a relative track and record number. The addresses must then be 
stored in a table that is searched when a record is to be retrieved. Disadvantages are that 
cross-referencing can be used efficiently only with a small data set, storage is required 
for the table, and processing time is required for searching and updating the table. 

A more common, but somewhat complex, technique for organizing the data set involves 
the use of indirect addressing. In indirect addressing, the address of each record in the 
data set is determined by a mathematical manipulation of the key. This manipulation is 
referred to as randomizing or conversion. Since a number of randomizing procedures 
could be used, no attempt is made here to describe or explain those that might be most 
appropriate for your data set. 
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Referring to a Record in a Direct Data Set 



Once you have determined how your data set is to be organized, you must consider how 
the individual records will be referred to when the data set is updated or new records are 
added. This is important for determining whether a return address will be required when 
the data is created and, if so, in what form the return address will be used. The record 
identification can be represented in any of the following forms: 

Relative Block Address: You specify the relative location of the record (block) within the 
data set as a 3 -byte binary number. This type of reference can be used only with 
format-F records. The system computes the actual track and record number. The relative 
block address of the first block is 0. 

Relative Track Address: You specify the relative track as a 2-byte binary number and the 
actual record number on that track as a 1-byte binary number. The relative track address 
of the first track is 0. 

Relative Track or Block Address and Actual Key: In addition to the relative track or block 
address, you specify the address of a virtual-storage location containing the record key. 
The system computes the actual track address and searches for the record with the 
correct key. 

Actual Address: You supply the actual address in the standard 8-byte 

form — MBBCCHHR. Remember that the use of an actual address may force you to 

indicate that the data set is unmovable. 

Extended Search: You request that the system begin its search with a specified starting 
location and continue for a certain number of records or tracks. This same option can be 
used to request a search for unused space in which a record can be added. 

To use the extended search option, you must indicate in the DCB the number of tracks 
(including the starting track) or records (including the starting record) that are to be 
searched. If you indicate a number of records, the system may actually examine more 
than this number. In searching a track, the system searches the whole track (starting with 
the first record); it therefore may examine records that precede the starting record or 
follow the ending record. 

Exclusive Control for Updating: When more than one task is referring to the same data 
set, exclusive control of the block being updated is required to prevent simultaneous 
reference to the same record. Rather than issuing an ENQ macro instruction each time 
you update a block, you can request exclusive control through the MACRF field of the 
DCB and the type operand of the READ macro. The coding example in Figure 61 
illustrates the use of exclusive control. After the READ macro instruction is executed, 
your task has exclusive control of the block being updated. No other task in the system 
requesting access to the block is given access until the operation started by your WRITE 
macro is complete. If, however, the block is not to be written, you can release exclusive 
control using the RELEX macro instruction. 



128 OS/VS2 MVS Data Management Services Guide 



Page of GC26-3875-0 
Revised August 31, 1978 
ByTNLGN26-0915 

Feedback Option: This option specifies that the system provide the address of the record 
requested by a READ or WRITE macro instruction. This address may be in the same 
form that was presented to the system in the READ or WRITE macro instruction, or as 
an 8-byte actual address. This option can be specified in the OPTCD parameter of the 
DCB and in the READ or WRITE macro instruction. If this option is omitted from the 
DCB but is requested in a READ or WRITE macro instruction, an 8-byte actual address 
is returned to the user. 

The feedback option is automatically provided for a READ macro instruction requesting 
exclusive control for updating. This feedback will be in the form of an actual address 
(MBBCCHHR) unless feedback was specified in the OPTCD field of the DCB. In this 
case, feedback is returned in the format of the addressing scheme used in the problem 
program (an actual or a relative address). When a WRITE or RELEX macro instruction 
is issued (which releases the exclusive control that was gotten for the READ request), 
the system will assume that the addressing scheme used for the WRITE or RELEX 
macro instruction is in the same format as the addressing scheme used for feedback in 
the READ macro instruction. 



Creating a Direct Data Set 



Once the organization of a direct data set has been determined, the process of creating it 
is almost identical to that of creating a sequential data set. The BSAM DCB macro 
instruction should be used with the WRITE macro instruction (the form used to create a 
direct data set). The following parameters must be specified in the DCB macro 
instruction: 

. DSORG=PS or PSU 

• DEVD=D A or omitted 

. MACRF=WL 

The DD statement must indicate direct-access (DSORG=DA or DAU). If keys are used, 
a key length (KEYLEN) must also be specified. Record length (LRECL) need not be 
specified but may be used to provide compatibility with sequential access method 
processing of this data set. 

It is possible to create a direct data set using QSAM (no keys allowed) or BSAM (with 
or without keys and the DCB specifies MACRF=W). However, this method is not 
recommended because when you access this direct data set, you cannot request a 
function which requires the information in the capacity record (RO) data field. For 
example, the following restrictions would apply: 

• Variable-length, undefined-length, or variable-length spanned record processing is not 
allowed. 

• The WRITE add function with extended search for fixed-length records (with or 
without track overflow) is not allowed. 

If a VIO data set is opened for processing with the extended search option, the 
DEBENDCC and DEBENDHH fields of the DEB will reflect the real address of the last 
record written during the BDAM create step. This is necessary to prevent BDAM from 
searching unused tracks. The information needed to determine the data set size is written 
in the DSCB during the close of the DCB used in the create step. Therefore, if this data 
set is being created and processed by the same program, and the DCB used for creating 
the data set has not been closed before opening the DCB to be used for processing, the 
resultant beginning and ending CCHH will be equal. 

If a direct data set is created and updated or read within the same job step, and the 
OPTCD parameter is used in the creation, updating, or reading of the data set, different 
DCBs and DD statements should be used. 
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If you are using direct addressing with keys, you can reserve space for future format-F 
records by writing a dummy record. To reserve or truncate a track for format-U or 
format-V records, write a capacity record. The capacity record (RO) contains a 7-byte 
data field (CCHHRLL) where CCHHR is the ID of the last record on the track, and LL 
is the number of unused bytes on the track. If a WRITE SZ macro is issued for a track 
with no records, R is zero and LL is the entire length of the track. 

Format-F records are written sequentially as they are presented. When a track is filled, 
the system automatically writes the capacity record and advances to the next track. 
Because of the form in which relative track addresses are recorded, direct data sets 
whose records are to be identified by means other than actual address must be limited in 
size to no more than 65,536 tracks for the entire data set. 

Tape-to-Disk — Direct Data Set: In the example problem in Figure 59, a tape containing 
204-byte records arranged in key sequence is used to create a direct data set. A 4-byte 
binary key for each record ranges from 1000 to 8999, so space for 8000 records is 
requested. 



//DAOUTPUT DD 

// 
//TAPINPUT DD 



DSNAME=SLATE . INDEX . WORDS , DCB= ( DSORG=DA , 
BLKSIZE=200 , KEYLEN=4 , RECFM=F ) , SPACE=( 204 , 8000 ) , 
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DEVD=DA , S YNAD=CHECKER , 

EODAD=INPUTEND,MACRF=(GL), 



Figure 59. Creating a Direct Data Set 
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Adding or Updating Records on a Direct Data Set 



The techniques for adding records to a direct data set depend on the format of the 
records and the organization used. 

Format-F With Keys: Adding a record amounts to essentially an update by record 
identification. The reference to the record can be made by either a relative block address 
or a relative track address. 

If you attempt to add a record by relative block address, the system converts the address 
to a relative track address. That track is searched and the new record written in place of 
the first dummy record on the track. If there is no dummy record on the track, you are 
informed that the write operation did not take place. If you request the extended search 
option, the new record will be written in place of the first dummy record found within 
the search limits you specify. If none is found, you are notified that the write operation 
could not take place. In the same way, a reference by relative track address causes the 
record to be written in place of the first dummy record found on that track or the first within 
the search limits, if requested. If extended search is used, the search begins with the first record 
on the track. Without extended search, the search may start at any record on the track. There- 
fore, records which were added to a track are not necessarily located on that track in the same 
sequence in which they were written. 

Format-F Without Keys: Here too, adding a record is really updating a dummy record 
already in the data set. The main difference is that dummy records cannot be written 
automatically when the data set is created. You will have to use your own method for 
flagging dummy records. The update form of the WRITE macro instruction 
(MACRF=W) must be used rather than the add form (MACRF=WA). 

You will have to retrieve the record first (using a READ macro instruction), test for a 
dummy record, update, and write. 

Format-V or Format-U With Keys: The technique used to add records in this case 
depends on whether records are located by indirect addressing or a cross-reference table. 
If indirect addressing is used, you must at least initialize each track (write a capacity 
record) even if no data is actually written. That way the capacity record indicates how 
much space is available on the track. If a cross-reference table is used, you should 
exhaust the input and then initialize enough succeeding tracks to contain any additions 
that might be required. 

To add a new record, use a relative track address. The system examines the capacity 
record to see if there is room on the. track. If there is, the new record is written. Under 
the extended search option, the record is written in the first available area within the 
search limit. 

Format-V or Format-U Without Keys: Because a record of this type does not have a key, 
you ca^n refer to the record only by its relative track or actual address (direct addressing 
only). When you add a record to this data set, you must retain the relative track or actual 
address data (for example, by updating your cross-reference table). The extended search 
option is not allowed because this option requires keys. 

Tape-to-Disk Add — Direct Data Set: The example in Figure 60 involves adding records 
to the data set created in the last example. Notice that the write operation adds the key 
and the data record to the data set. If the existing record is not a dummy record, an 
indication is returned in the exception code of the DECB. For that reason, it is better to 
use the WAIT macro instruction instead of the CHECK macro instruction to test for 
errors or exceptional conditions. 
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//DIRADD DD 
//TAPEDD DD 
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: igure 60. Adding Records to a Direct Data Set 
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Figure 61. Updating a Direct Data Set 



Tape-to-Disk Update — Direct Data Set: The example in Figure 61 is similar to that in 
Figure 60, but involves updating rather than adding. There is no check for dummy 
records. The existing direct data set contains 25,000 records whose 5 -byte keys range 
from 00001 to 25000. Each data record is 100 bytes long. The first 30 characters are to 
be updated. Each input tape record consists of a 5-byte key and a 30-byte data area. 
Notice that only data is brought into virtual storage for updating. 
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Consideration for User Labels: User labels, if desired, must be created when the data set 
is created. They may be updated, but not added or deleted, during processing of a direct 
data set. When creating a multivolume direct data set using BSAM, you should turn off 
the header exit entry after OPEN and turn on the trailer label exit entry just before 
issuing the CLOSE. This eliminates the end-of-volume exits. The first volume, containing 
the user label track, must be mounted when the data set is closed. If you have requested 
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exclusive control, OPEN and CLOSE will ENQ and DEQ to prevent simultaneous 
reference to user labels. 

Consideration for using the 2305 Fixed Head Storage: When a data set on a 2305 device 
is to be used by several tasks simultaneously, or when overlapping I/O (successive 
WRITEs issued without an intervening CHECK or WAIT) is used, the following 
combination may produce overlaying of records: 

• WRITE-add processing 

• Fixed records with or without track overflow 
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PART 3: DATA SET DISPOSITION AND SPACE 
ALLOCATION 

Allocating Space on Direct-Access Volumes 

When direct-access storage space is required for a data set, you specify the amount of 
space needed and the device type, and the operating system selects the device and 
allocates the space accordingly. This arrangement provides for flexible and efficient use 
of devices and available storage space, and relieves you of considering the details 
involved in efficient space control. 

Before a direct-access volume can be used for data storage, it must be initialized by 
either of the utility programs IBCDASDI or IEHDASDR. The utilities' functions include 
in part: 

• Creating the standard 80-byte volume label and writing it on cylinder 0, track 0, of 
the volume. 

• Initializing the volume table of contents (VTOC). The location of the VTOC depends 
on the conventions your installation uses in initializing the volume. 

• Writing the home address (HA) and capacity record (R0) for each track. 

• Checking tracks and making alternate track assignments if necessary. 

When the data set is to be stored on a direct-access volume, you must supply, in the DD 
statement, control information designating the amount of space to be allocated and the 
manner in which it is to be allocated. 

Note: IEHDASDR and IBCDASDI cannot be used for an MSS 3330 virtual volume. 
The Access Method Services utility, CREATEV, must be used. See OS/ VS Mass 
Storage System (MSS) Services for Space Management for a description of the 
CREATEV command. 

Specifying Space Requirements 

The amount of space required can be specified in blocks, tracks, or cylinders. If you want 
to maintain device independence, specify your space requirements in blocks. If your 
request is in tracks or cylinders, you must be aware of such device considerations as 
cylinder and track capacity. 

Cylinder allocation allows faster input/output of sequential data sets than does track 
allocation. The exceptions are reading records in fixed standard format on a non-RPS 
device without using chained scheduling, and writing any records without using chained 
scheduling. Note: These two exceptions do not apply to 5740- AM3. 

Allocation by Blocks: When the amount of space required is expressed in blocks, you 
must specify the number and average length of the blocks within the data set, as in this 
example: 

// DD SPACE=( 300, (5000, 100)), . . . 

300 = average block length in bytes 
5000 = primary quantity (number of blocks) 
100 = secondary quantity, to be allocated if the primary quantity is not 
sufficient (in blocks) 

Note that when average block length and secondary space allocation are being used, the 
BLKSIZE parameter specified must be equal to the maximum block length. 
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From this information, the operating system estimates and allocates the number of tracks 
required. Space is always in whole tracks. You may also request that the space allocated 
for a specific number of blocks begin and end on cylinder boundaries. 

You must be certain that both the quantity and the increment are large enough to contain 
the largest block to be written. Otherwise, all of the space requested is allocated but 
erased as the system tries to find a space large enough for the record. 

Allocation by Tracks or Cylinders: The amount of space required can be expressed in 
tracks or cylinders, as in these examples: 

// DD SPACE=(TRK,( 100,5) ) f ... 
// DD SPACE=(CYL,(3,1 ) ), . . . 

Allocation by Absolute Address: If the data set contains location-dependent information 
in the form of an absolute track address (MBBCCHHR), space should be requested with 
respect to the number of tracks and the beginning address, as in this example: 

// DD SPACE=(ABSTR,( 500,20 ) ),UNIT=23 14, . . . 

where 500 tracks are required, beginning at relative track 20, which is cylinder 1, track 0. 

Allocation of Mass Storage System (MSS) Virtual Volumes: When the data set is to be 
stored on an MSS virtual volume, a volume group (MSVGP) parameter may be specified 
instead of using the SPACE parameter on the DD card. Before the MSVGP parameter 
can be used, the volume group must be identified to MSS by the utility program 
IDCAMS. 

Allocation of MSS virtual volume space should be in multiples of cylinders with 
secondary allocation a multiple of the primary to insure maximum space usage and 
minimum fragmentation. 

Additional Space Allocation Options: The DD statement provides you with a great deal of 
flexibility in specifying space requirements. These options are described in detail in 
OS/VS2 JCL. 



Estimating Space Requirements 



To determine how much space your data set requires, you must consider these variables 
for the device type: 

• Track capacity 

• Tracks per cylinder 

• Cylinders per volume 

• Data length (blocksize) 

• Key length 

• Device overhead 

Figure 62 lists the physical characteristics of a number of direct-access storage devices. 

The term device overhead refers to the space required on each track for hardware data, 
that is, address markers, count areas, gaps between records, record 0, etc. Device 
overhead varies with each device and depends also on whether the blocks are written 
with keys. To compute the actual space required for each block including device 
overhead, you can use the formulas in Figure 63. Note that any fraction of a byte must 
be ignored. For example, if the formula gives 15.644 bytes, you must allocate 15 bytes. 
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DL is data length. 
KL is key length. 

' This value is different from the maximum block size per track because the formula for the last block on the track includes 
an overhead for this device. 

2 The formula for the last block on the track is 45+KL+OL. 

3 The formula for the last block on the track is DL. 

4 The Mass Storage System (MSS) virtual volumes assume the characteristics of the 3330/3333. Model I. 

Figure 63. Direct-Access Device Overhead Formulas 

The formulas can be combined in the following way: 

If you intend to specify your space requirements in tracks (TRK) or cylinders (CYL), 
your estimate should be made as shown above. If you request absolute tracks (ABSTR), 
remember that you cannot allocate track 0, cylinder 0. The amount of space required for 
the VTOC will reduce the space available on the rest of the volume. 

If you specify your space requirements in average block length, the system performs the 
computations for you. 

Because a sequential data set and a direct data set are created in the same way, the 
estimate and specification of space requirements are identical. If you use the WRITE SZ 
macro instruction, your secondary allocation for a direct data set should be at least 2 
tracks. Space allocation for a partitioned data set requires that you also consider the 
space used for the directory. Similarly, allocation for an indexed sequential data set 
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requires that you consider the space needed for the prime area, index areas, and overflow 
areas. 



Allocating Space for a Partitioned Data Set 



What is the average size of the members to be stored on your direct-access volume? How 
many members will fit on the volume? Will you need directory entries for the member 
names only or will aliases be used? How many? Will members be added or replaced 
frequently? All of these questions must be answered if you are to estimate your space 
requirements accurately and use the space efficiently. Note, too, that a partitioned data 
set cannot extend beyond one volume. 

If your data set will be quite large, or you expect to do a lot of updating, it might be best 
to allocate a full volume. If it will be small or seldom subject to change, you should make 
your estimate as accurate as possible to avoid wasted space or wasted time used for 
recreating the data set. 

If the average member length is close to or less than the track length, the most efficient 
use of the direct-access storage space may be made with a block size of 1/3 or 1/2 the 
track length. For load modules, the linkage editor ignores the specified maximum block 
size and uses the maximum block size for the device. Program fetch always ignores 
BLKSIZE. It may be a good practice to indicate a block length equal to track capacity, 
for example, BLKSIZE=7294 for a 2314 disk. You might then ask for either 100 tracks, 
or 5 cylinders, thus allowing for 729,400 bytes of data. 

Assuming an average length of 70,000 bytes for each member, you need space for at 
least 10 directory entries. If each member also has an average of three aliases, space for 
an additional 30 directory entries is required. 

Space for the directory is expressed in 256-byte blocks. Each block contains from 3 to 
20 entries, depending on the length of the user data field. If you expect 40 directory 
entries, request at least 8 blocks. Any unused space on the last track of the directory is 
wasted unless there is enough space left to contain a block of the first member. 
Therefore, the most advisable request in this case would be for 17 blocks. 

Any of the following space specifications would cause the same size allocation for a 23 1 4 
disk: 

SPACE=(7294,(100„10)) 

SPACE=(CYL,(5„10)) 

SPACE=(TRK,(100„10)) 

Although a secondary allocation increment has been omitted in these examples, it could 
have been supplied to provide for extension of the member area. The directory size, 
however, cannot be extended. 



Allocating Space for an Indexed Sequential Data Set 



An indexed sequential data set has three areas: prime, index, and overflow. Space for 
these areas can be subdivided and allocated as follows: 

• Prime area — If you request a prime area only, the system automatically uses a portion 
of that space for indexes, taking one cylinder at a time as needed. Any unused space 
in the last cylinder used for index will be allocated as an independent overflow area. 
More than one volume can be used in most cases, but all volumes must be for devices 
of the same device type. 

• Index area — You can request that a separate area be allocated to contain your 
cylinder and master indexes. The index area must be contained within one volume, but 
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this volume can be on a device of a different type than the one that contains the prime 
area volume. If a separate index area is requested, you cannot catalog the data set with 
a DD statement. 

If the total space occupied by the prime area and index area does not exceed one 
volume, you can request that the separate index area be embedded in the prime area 
(to reduce access arm movement) by indicating an index size in the SPACE parameter 
of the DD statement defining the prime area. 

If you request space for prime and index areas only, the system automatically uses any 
space remaining on the last cylinder used for master and cylinder indexes for overflow, 
provided the index area is on a device of the same type as the prime area. 

• Overflow area — Although you can request an independent overflow area, it must be 
contained within one volume. If no specific request for index area is made, then it will 
be allocated from the specified independent overflow area. 

To request that a designated number of tracks on each cylinder be used for cylinder 
overflow records, you must use the CYLOFL parameter of the DCB macro 
instruction. The number of tracks that you can use on each cylinder equals the total 
number of tracks on the cylinder minus the number of tracks needed for track index 
and for prime data, that is: 

Usable tracks = total tracks - (track index tracks + prime data tracks) 

Note that when you create a 1 -cylinder data set, ISAM reserves 1 track on the last 
cylinder for the end-of-file filemark. 

When you request space for an indexed sequential data set, the DD statement must 
follow a number of conventions, as shown below and summarized in Figure 68. 

• Space can be requested only in cylinders, SPACE=(CYL,(...)), or absolute tracks, 
SPACE=(ABSTR, (...)). If the absolute track technique is used, the designated tracks 
must make up a whole number of cylinders. 

• Data set organization (DSORG) must be specified as indexed sequential (IS or ISU) 
in both the DCB macro instruction and the DCB parameter of the DD statement. 

• All required volumes must be mounted when the data set is opened; that is, volume 
mounting cannot be deferred. 

• If your prime area extends beyond one volume, you must indicate the number of units 
and volumes to be spanned, for example, UNIT=(2314,3),VOLUME=(,„3). 

• You can catalog the data set using the DD statement parameter DISP=(,CATLG) 
only if the entire data set is defined by one DD statement; that is, if you did not 
request a separate index or independent overflow area. 
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Figure 64. Requests for Indexed Sequential Data Sets 



As your data set is created, the operating system builds the track indexes in the prime 
data area. Unless you request a separate index area or an embedded index area, the 
cylinder and master indexes are built in the independent overflow area. If you did not 
request an independent overflow area, the cylinder and master indexes are built in the 
prime area. 

If an error is encountered during allocation of a multivolume data set, the IEHPROGM 
utility program should be used to scratch the DSCBs of the data sets that were 
successfully allocated. The IEHLIST utility program can be used to determine whether or 
not part of the data set has been allocated. The IEHLIST utility progr^rn is ajso useful to 
determine whether space is available or whether identically named data sets exist before 
space allocation is attempted for indexed sequential data sets. These utility programs are 
described in OS/ VS Utilities. 

Specifying a Prime Data Area 

To request that the system allocate space and subdivide it as required, you should code: 

//ddname DD DSNAME=dsname,DCB=DSORG=IS, 

// SPACE=(CYL, quantity, CONTIG ) , UNIT=unitname, 

// DISP=( ,KEEP), 

You can accomplish the same type of allocation by qualifying your dsname with the 
element indication (PRIME). This element is assumed if omitted. It is required only if 
you request an independent index or overflow area. To request an embedded index area 
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when an independent overflow area is specified, you must indicate 
DSNAME=dsname (PRIME). To indicate the size of the embedded index, 
you specify SPACE=(CYL,(quantity„index size)). 



Specifying a Separate Index Area 



To request a separate index area, other than an embedded area as described above, you 
must use a separate DD statement. The element name is specified as (INDEX). The 
space and unit designations are as required. Notice that only the first DD statement can 
have a data definition name. The data set name (dsname) must be the same. 

//ddname DD DSNAME=dsname( INDEX ) , 

// DD DSNAME=dsname( PRIME ) , 



Specifying an Independent Overflow Area 

A request for an independent overflow area is essentially the same as for a separate index 
area. Only the element name, OVFLOW, is changed. If you do not request a separate 
index area, only two DD statements are required. 

//ddname DD DSNAME=dsname( INDEX ) , 

// DD DSNAME=dsname( PRIME ) , 

// DD DSNAME=dsname( OVFLOW), 

Calculating Space Requirements for an Indexed Sequential Data Set 

To determine the number of cylinders required for an indexed sequential data set, you 
must consider the number of blocks that will fit on a cylinder, the number of blocks that 
will be processed, and the amount of space required for indexes and overflow areas. 
When you make the computations, consider how much additional space is required for 
device overhead. Figures 62 and 63 show device capacities and overhead formulas. In the 
formulas that follow, the length of the last block (or only block) must include device 
overhead as given in Figure 63 as Bn. 

Blocks = I + ((Track capacity - Length of the last block)/(Lcngth of other blocks)) 
per track 

Bt = 1 + ((Ct-Bn)/Bi) 

The following eight steps summarize calculation of space requirements for an indexed 
sequential data set. 

Step 1 

Once you know how many records will fit on a track and the maximum number of 
records you expect to create, you can determine how many tracks you will need for your 
data. 

Number of tracks required = (Maximum number of blocks/Blocks per track) + I 

ISAM load mode reserves the last prime data track for the filemark. 

Example: Assume that a 200,000 record part-of-speech dictionary is stored on an IBM 
3330 Disk Storage, using the 3336 disk pack, as an indexed sequential data set. Each 
record in the dictionary has a 12-byte key (the word itself) and an 8-byte data area 
containing a part-of-speech code and control information. Each block contains 50 
records; LRECL=20 and BLKSIZE=1000. Using the formula from Figure 63, we find 
that each track will contain 10 blocks or 500 records. A total of 401 tracks will be 
required for the dictionary. 

Bt = 1 + 13,165 -(191 + 12+ 1000) = I + 1 1 ,962 =1+9=10 

191 + 12+ 1000 1203 

Records per track = ( 10 blocks)(50 records per block) = 500 

Prime data tracks required (T) = 200,000 records + 1 = 401 

500 records per track 
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Step 2 

You will want to anticipate the number of tracks required for cylinder overflow areas. 
The computation is the same as for prime data tracks, but you must remember that 
overflow records are unblocked and a 10-byte link field is added. Remember, if you 
exceed the space allocated for any cylinder overflow area, an independent overflow area 
is required. Those records are not placed in another cylinder overflow area. 

Overflow records = I + Track capacity - Length of last overflow record 
per track (Ot) Length of other overflow records 

Ot = 1 + ((Ct-Rn)/Ri) 

Example: Approximately 5000 overflow records are expected for the data set described 
in step 1. Since 56 overflow records will fit on a track, 90 overflow tracks are required. 
This is 90 overflow tracks for 401 prime data tracks, or approximately 1 overflow track 
for every 4 prime data tracks. Since the 3336 disk pack has 19 tracks per cylinder, it 
would probably be best to allocate 4 tracks per cylinder for overflow. 

Ot=l + I3,I65-(I9I + 12 + 20+ 10) =1+ 12,932 = I + 55 = 56 

191 + 12 + 20+10 233 

Overflow tracks required = 5000 records = 90 

56 records per track 

Overflow tracks per cylinder (Oc) = 4 

Step 3 

You will have to set aside space in the prime area for track index entries. There will be 
two entries (normal and overflow) for each track on a cylinder that contains prime data 
records. The data field of each index entry is always 10 bytes long. The key length 
corresponds to the key length for the prime data records. How many index entries will fit 
on a track? 

Index entries = 1 + Track capacity - Length of last index entry 
per track (It) Length of other index entries 

It = I +((Ct-En)/Ei) 

Example: Again assuming use of a 3336 disk pack and records with 12-byte keys, we 
find that 61 index entries will fit on a track. 

It m I + 13,165 - ( 191 + 12+ 10 ) = I + 12.952 = I + 60 = 61 

191 +(12+ 10) 213 

Step 4 

The number of tracks required for track index entries will depend on the number of 
tracks per cylinder and the number of track index entries per track. Any unused space on 
the last track of the track index can be used for any prime data records that will fit. 

Number of track index = 2(Tracks per cylinder-overflow tracks per cylinder) + I 
tracks per cylinder (Ic) Index entries per track + 2 

Ic = (2(Tc-Oc)+l)/(It+2) 

Note that for variable-length records or when a prime data record will not fit on the last 
track of the track index, the last track of the track index is not shared with prime data 
records. In such a case, if the remainder of the division is less than or equal to 2, drop the 
remainder. In all other cases, round the quotient up to the next integer. 

Example: The 3336 disk pack has 19 tracks per cylinder. You can fit 61 track index 
entries per track. Therefore, you need less than 1 track for each cylinder: 

Ic= 2(19-4)+ 1= 31 

61+2 63 

The space remaining on the track is (1-31/63) (13,165) = 6686 bytes. 
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This is enough for 6 blocks of prime data records. Since the normal number of blocks per 
track is 10, the blocks use 6/10 of the track, and the effective value of Ic is therefore 
1-6/10 = 2/5. 

Note that space is required on the last track of the track index for a dummy entry to 
indicate the end of the track index. The dummy entry consists of an 8-byte count field, a 
key field the same size as the key field in the preceding entries, and a 10-byte data field. 

Step 5 

Next you have to compute the number of tracks available on each cylinder for prime data 
records. You cannot include tracks set aside for cylinder overflow records. 



Prime d 
tracks pe 
cylinder 



ata /Tracks \ /Overflow tracksN /index tracks\ 
er = \per cylinder/ - \per cylinder /- \per cylinder/ 



Pc = Tc - Oc - Ic 

Example: If you set aside 4 cylinder overflow tracks, and you require 2/5 of a track for 
the track index, 14 3/5 tracks are available on each cylinder for prime data records. 

Pc= 19-4-2/5= 14 3/5 

Step 6 

The number of cylinders required to allocate prime space is determined by the number of 
prime data tracks required divided by the number of prime data tracks available on each 
cylinder. This area includes space for the prime data records, track indexes, and cylinder 
overflow records. 

Number of 

cylinders = Prime data tracks required/Prime data tracks per cylinder 

required 

C = T/Pc 

Example: You need 401 tracks for prime data records. You can use 14-3/5 tracks per 
cylinder. Therefore, 28 cylinders are required for your prime area and cylinder overflow 
areas. 

C = (40l)/(l4 3/5) = 27-f ~28 

Step 7 

You will need space for a cylinder index as well as track indexes. There is a cylinder 
index entry for each track index (for each cylinder allocated for the data set). The size of 
each entry is the same as the size of the track index entries; therefore, the number of 
entries that will fit on a track is the same as the number of track index entries. Unused 
space on a cylinder index track is not shared. 

Number of tracks 

required for = (Track indexes + I )/Index entries per track 

cylinder index 

Ci = (C+D/It 

Example: You have 28 track indexes (from Step 6). Since 61 index entries fit on a track 
(from Step 3), you need 1 track for your cylinder index. The remaining space on the last 
track is unused. 

Ci = (28 + D/61 = 29/61 = 0.475 < I 

Note that every time a cylinder index crosses a cylinder boundary, ISAM writes a dummy 
index entry that lets ISAM chain the index levels together. The addition of dummy 
entries can increase the number of tracks required for a given index level. To determine 
how many dummy entries will be required, divide the total number of tracks required by 
the number of tracks on a cylinder. If the remainder is 0, subtract 1 from the quotient. If 



Part 3: Data Set Disposition and Space Allocation 143 



the corrected quotient is not 0, calculate the number of tracks these dummy entries 
require. Also consider any additional cylinder boundaries crossed by the addition of these 
tracks and by any track indexes starting and stopping within a cylinder. 

Step 8 

If you have a data set large enough to require master indexes, you will want to calculate 
the space required according to the number of tracks for master indexes (NTM 
parameter) you specified in the DCB macro instruction or the DD statement. 

If the cylinder index exceeds the NTM specification, an entry is made in the master index 
for each track of the cylinder index. If the master index itself exceeds the NTM 
specification, a second-level master index is started. Up to three levels of master indexes 
are created if required. 

The space requirements for the master index are computed in the same way as those for 
the cylinder index. 

Number of tracks 

required for *= (Number of cylinder index tracks + 1)/Index entries per track 

master indexes 

M, = (Ci+1)/It whenCi>NTM 

M 2 = (M | + 1 )/It when M!>NTM 

M 3 = (M 2 +1)/It when M 2 > NTM 

Example: Assume that your cylinder index will require 22 tracks. Since large keys are 
used, only 10 entries will fit on a track. Assuming that NTM was specified as 2, 3 tracks 
will be required for a master index, and two levels of master index will be created. 

M, = (22+0/10 = 2.3 

Note that every time a master index crosses a cylinder boundary, ISAM writes a dummy 
index entry that lets ISAM chain the index levels together. The addition of dummy 
entries can increase the number of tracks required for a given index level. To determine 
how many dummy entries will be required, divide the total number of tracks required by 
the number of tracks on a cylinder. If the remainder is 0, subtract 1 from the quotient. If 
the corrected quotient is not 0, calculate the number of tracks these dummy entries 
require. Also consider any additional cylinder boundaries crossed by the addition of these 
tracks and by any track indexes starting and stopping within a cylinder. 

Summary: Indexed Sequential Space Requirement Calculations 

1 . How many blocks will fit on a track? 

Bt = I + ((Ct-Bn)/Bi) 

2. How many overflow records will fit on a track? 

Ot = I + ((Ct-Rn)/Ri) 

3. How many index entries will fit on a track? 

It = 1 + ((Ct-En)/Ei) 

4. How many track index tracks are needed per cylinder? 

Ic = (2(Tc-Oc)+l)/(It+2) 

5. How many tracks on each cylinder can be used for prime data records? 

Pc = Tc-Oc-lc 

6. How many cylinders are needed for the prime data area? 

C = T/Pc 
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7. How many tracks are required for the cylinder index? 

Ci = (C+1)/lt 

8. How many tracks are required for master indexes? 

M = (Ci+1)/It 



Control and Disposition of Data Sets 

You specify two kinds of status and disposition information for the data sets you use for 
your processing by coding DISP=(status,disposition) in the disposition field of the DD 
statement. The first kind deals with the status of the data set when you begin processing 
and the relationship of the data set to other job steps in your job or other jobs. The 
second deals with what is to be done with the data set when you have completed 
processing. In the latter case, you can take advantage of the catalog of the operating 
system. 

A data set that is being used for input has a status of OLD. If it can be used by more 
than one job, the status should be specified as SHR. If you are going to add to the input 
data set, specify MOD. The system automatically positions the access mechanism after 
the last record when the data set is opened. A new output data set should be indicated as 
NEW. 

Having identified the status of the data set at the beginning of your job step, you should 
specify how you want it disposed of at the end of processing. If the disposition is to be 
unchanged, you need not specify anything. The status of an existing data set remains 
unchanged; a new data set is deleted. The requested disposition is performed at the end 
of the job step. A data set to be used in a later job can be kept (KEEP) until a 
subsequent request is made to delete it. If the data set is to be used by more than one job 
step in the same job, you can specify that it is to be passed (PASS). 

If you specify the CATLG disposition, the data set name is recorded in the catalog by 
the system and its volume is noted. An old data set can subsequently be removed from 
the catalog if you specify UNCATLG. 

If you wish, you can specify one disposition to be performed if the job step terminates 
normally, and a different disposition to be performed if the job step terminates 
abnormally. For example, you can specify DISP=(OLD,DELETE,KEEP) if you wish to 
delete a data set under normal conditions, but wish to keep it if processing is abnormally 
terminated. For normal termination, you can specify any disposition — PASS, KEEP, 
DELETE, CATLG, or UNCATLG; for abnormal termination, you can specify any 
disposition except PASS. 

Routing Data Through the System Input and Output Streams 

The job entry subsystem is a system facility that provides spooling and scheduling of 
input and output data streams. 

Spooling includes two basic functions: 

• Input streams are read from the input device and stored on an intermediate storage 
device in a format convenient for later processing by the system and by the user's 
program. 

• Output streams are similarly stored on an intermediate device until a convenient time 
for printing or punching. 

Scheduling provides the highest degree of system availability through the orderly use of 
system resources that are the objects of contention. 
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With spooling, unit record devices are used at full rated speed if enough buffers are 
available, and they are used only for the time needed to read, print, or punch the data. 
Without spooling, the device is occupied for the entire time that a job is doing other 
processing. Also, because data is stored instead of being transmitted directly, output can 
be queued in any order and scheduled by class and by priority within each class. 

You enter data into the system input stream by preceding it with a DD * or DD DATA 
JCL statement. This is a SYSIN data set. 

Your output data can be printed or punched from a SYSOUT data set, which is called the 
output stream. You code the SYSOUT keyword parameter in your DD statement and 
designate the appropriate output class. For example, SYSOUT= A requests output class 
A. The class-device relationship is established for each installation, and a list of devices 
assigned to each output class will enable you to select the appropriate one. Refer to 
OS/VS2 JCL for further information on SYSIN and SYSOUT parameters. 

SYSIN and SYSOUT must be BSAM or QSAM data sets and you open and close them in 
the same manner as any other data set processed on a unit record device (except when 
multiple DCBs are used to write to the same output class, the records are not 
interspersed.) The DCB exit routine will be entered in the usual manner if you specify it 
in an exit list. 

When you use QSAM with fixed-length blocked records or BSAM, the DCB block size 
parameter does not have to be a multiple of logical record length (LRECL) if the block 
size is specified through the SYSOUT DD statement. Under these conditions, if block 
size is greater than LRECL but not a multiple of LRECL, block size is reduced to the 
nearest lower multiple of LRECL when the data set is opened. This feature allows a 
cataloged procedure to specify blocking for SYSOUT data sets, even though your 
LRECL is not known to the system until execution. 

Therefore, the SYSOUT DD statement of the go step of a compile-load-go procedure 
can specify block size without block size being a multiple of LRECL. For further 
information, refer to OS/VS2 JCL. 

Because a SYSOUT data set is written on a direct-access device, you should omit the 
DEVD operand in the DCB macro instruction, or should code DEVD=DA. Because 
SYSIN and SYSOUT data sets are spooled on intermediate devices, you should also 
avoid using device dependent macro instructions (such as FEOV, CNTRL, PRTOV, 
BSP, or SETPRT) in processing these data sets. (See the sections, "Device Control" and 
"Device Independence.") 

The job entry subsystem controls all blocking and deblocking of your data to optimize 
system operation and ignores the number of channel programs (NCP) you specify. The 
block size (BLKSIZE) and number of buffers (BUFNO) specified in your program have 
no correlation with what is actually used by the job entry subsystem. Therefore, you can 
select the blocking factor that best fits your application program with no effect on the 
spooling efficiency of the system. For QSAM applications, move mode is as efficient as 
locate mode. 

All record formats are allowed, except that spanned records (RECFM=VS or VBS) 
cannot be specified for SYSIN. A record format of FIXED is supplied if it is not 
specified for SYSIN. 

The logical record length value (JFCLRECL field in the JFCB) is filled in with the 
logical record length value of the input data set. This value is increased by four if the 
record format is variable (RECFM=V or VB). The logical record length may be a size 
other than the size of the input device, if the SYSIN input stream is supplied by an 
internal reader. The job entry subsystem will supply a value in the JFCLRECL field of 
the JFCB if that field is found to be zero. 
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The blocksize value (JFCBLKSI field in the JFCB) is filled in with the blocksize value of 
the input data set. This value is increased by four greater than the value calculated for 
the logical record value (that is, input data set logical record length +4) if the record 
format is variable (RECFM=V or VB). The job entry subsystem will supply a value in 
the JFCBLKSI field of the JFCB if that field is found to be zero. 

Your program is responsible for printing format, pagination, and header control. You can 
supply control characters for SYSOUT data sets in the normal manner by specifying 
ANSI or machine characters in the DCB. Standard controls are provided by default if 
they are not specified. The length of output records must not exceed the allowable 
maximum length for the ultimate device. Cards can be punched in EBCDIC mode only. 

Your SYNAD routine will be entered if an error occurs during data transmission to or 
from an intermediate storage device. Again, because the specific device is indeterminate, 
your SYNAD routine code should be device independent. 



Concatenating Sequential and Partitioned Data Sets 



Two or more sequential or partitioned data sets can be automatically retrieved by the 
system and processed successively as a single data set. This reading technique is known 
as concatenation. A maximum of 255 data sets (16, if partitioned) can be concatenated, 
but they must be used only for input. 

To save time when processing two consecutive data sets on a single volume, you specify 
LEAVE in your OPEN macro instruction. Concatenated data sets cannot be read 
backward. 

When data sets are concatenated, the system treats the group as a single data set and 
only one data extent block (DEB) is constructed. Thus, it is important to consider the 
characteristics of the individual data sets being concatenated. Data sets with like 
characteristics are those that may be processed correctly using the same data control 
block (DCB), input/output block (IOB), and channel program. Any exception makes 
them unlike. Concatenated partitioned data sets are always treated as like and use the 
attributes of the first data set only. You must inform the system by modifying the 
DCBOFLGS field of the DCB if unlike data sets are concatenated (this is not required 
for spool data sets, because EOV automatically treates them as unlike data sets). The 
indication must be made before the end of the current data set is reached. You must set 
bit 4 to 1 by using the instruction OI DCBOFLGS,X'08' as described in "Modifying the 
Data Control Block." If bit 4 of the DCBOFLGS field is 1, end-of- volume processing for 
each data set will issue a CLOSE for the data set just read and an OPEN for the next 
concatenated data set. This opening and closing procedure updates the fields in the DCB 
and, if necessary, builds a new IOB and a new channel program. If the buffer pool was 
obtained automatically by the open routine, the procedure also frees the buffer pool and 
obtains a new one for the next concatenated data set. The procedure does not issue a 
FREEPOOL for the last concatenated data set. Unless you have some way of 
determining the characteristics of the next data set before it is opened, you should not 
reset the DCBOFLGS field to indicate like characteristics during processing. When you 
concatenate data sets with unlike attributes, no EOV exits are taken. 

When unlike data sets have been concatenated, you should not issue multiple input 
requests, that is, a series of READ or GET macro instructions, in your program. If you 
do, you will have to arrange some way to determine which requests have been completed 
and which must be reissued. In any case, the GET or READ macro instruction that 
detected the end of data set will have to be reissued. Figure 65 illustrates a possible 
routine for determining when a GET or READ must be reissued. This restriction does 
not apply to like data sets since no open or close operation is necessary between data 
sets. 
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Figure 65. Reissuing a READ for Unlike Concatenated Data Sets 



When the change from one data set to another is made, label exits are taken as required; 
automatic volume switching is also performed for multiple-volume data sets unless they 
are partitioned. Your end-of -data-set (EODAD) routine is not entered until the last data 
set has been processed, except that for partitioned data sets, your EODAD routine 
receives control at the end of each member. At that time, you can process the next 
member or close the data set. 

You process a concatenation of partitioned data sets the same way you process a single 
partitioned data set with one exception. You must use the FIND macro instruction to 
begin processing a member; you cannot use the POINT (or NOTE) macro instruction 
until after the FIND macro instruction has been issued. Figure 49 shows how to process 
a single partitioned data set using FIND. If two members of different data sets in the 
concatenation have the same name, the FIND macro instruction determines the address 
of the first one in the concatenation. You would not be able to process the second one in 
the concatenation. The BLDL macro instruction provides the concatenation number of 
the data set to which the member belongs in the K field of the build list. See the section 
"BLDL — Construct a Directory Entry List" in Part 2 of this book. 

If issuing an RDJFCB macro, see the RDJFCB macro instruction in the OS/VS2 System 
Programming Library: Data Management. 



Rotational Position Sensing Considerations 



Direct-access storage devices with the rotational position sensing (RPS) feature (for 
example, the 3330) usually employ channel programs that are not compatible with 
direct-access storage devices that lack the RPS feature. Therefore, if you concatenate 
otherwise "like" data sets residing on devices both with and without the RPS feature, 
standard (nonRPS) channel programs will be used, with a resultant loss of the I/O 
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overlap efficiency of rotational position sensing. Concatenated partitioned data sets are 
always treated as "like" data sets, regardless of how the DCBOFLGS field is set in the 
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DCB. Data sets with undefined length records and track overflow (RECFM=UT 
specified in the DCB) are not processed with the RPS feature. 

On the other hand, if you concatenate sequential data sets with "unlike" attributes, you'll 
get RPS channel programs for the data sets residing on RPS devices, unless any following 
direct-access concatenations are nonRPS devices. 

Further discussion and examples of concatenated data sets are contained in OS/VS2 
JCL. 



Cataloging Data Sets 



The MVS operating system has a catalog structure consisting of a VSAM master catalog, 
VSAM user catalogs, and, optionally, control volumes (CVOLS). Figure 66 shows the 
MVS catalog structure. 
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Figure 66. MVS Catalog Structure 



There is one master catalog on each system. It is required and contains entries for system 
data sets. It is also the VSAM master catalog and does not have to be on the system 
residence volume. The master catalog contains a pointer to each user catalog. Both 
VSAM and nonVSAM data sets can be cataloged in a user catalog. 

NonVSAM data sets can be cataloged on control volumes (SYSCTLG data sets). The 
master catalog contains a pointer to each control volume. Data sets can be cataloged, 
uncataloged, or recataloged. For more information on using CVOLs in an MVS system, 
see OS/VS2 Using OS Catalog Management with the Master Catalog: CVOL 
Processor (for OS/VS2 MVS Data Management Selectable Unit VS2.03.808, see 
OS/VS2 MVS CVOL Processor). If a data set is not cataloged in the master catalog, 
the first name of a qualified data set name indicates the user catalog or control volume in 
which it is cataloged. A user catalog can also be connected to the VS2 system as a job 
catalog or a step catalog. 

Permanent Mass Storage System (MSS) data sets should be cataloged to allow efficient 
use of the Mass Storage Volume Control (MSVC) functions. For information on MSVC, 
see OS/VS Mass Storage System (MSS) Services: General Information. 
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Entering a Data Set Name in the Catalog 



The data set name of a nonVSAM data set can be entered in a master or user catalog 
through (1) job control language (DISP parameter), (2) Access Method Services 
(DEFINE command), or (3) catalog management macro instructions (CATALOG and 
CAMLST). A nonVSAM data set name can be entered in a control volume through JCL 
or the catalog management macros. VSAM data sets can only be cataloged by using 
Access Method Services. 

Access Method Services is also used to establish aliases for data set names and to 
connect user catalogs and control volumes to the master catalog. See OS/VS2 Access 
Method Services for information on how to use the Access Method Services commands. 
See OS/VS2 System Programming Library: Data Management for information on 
how to use the catalog management macro instructions. 



Generation Data Groups 



A generation data group is a group of related cataloged data sets. The manner in which 
these data sets are cataloged is what makes them a generation data group. Within a 
generation data group, the generations can have like or unlike DCB attributes and data 
set organizations. If the attributes and organizations of all generations in a group are 
identical, the generations can be retrieved together as a single data set. Each data set 
within a generation data group is called a generation data set. Generation data sets are 
sometimes called generations. 

There are advantages to grouping related data sets. Because the catalog management 
routines can refer to the information in a special index — called a generation index — in 
the catalog: 

• All of the data sets in the group can be referred to by a common name. 

• The operating system is able to keep the generations in chronological order. 

• Outdated or obsolete generations can be automatically deleted by the operating 
system. 

The management of a generation data group depends upon the fact that generation data 
sets have sequentially ordered names — absolute and relative names — that represent their 
age. The absolute generation name is the representation used by the catalog management 
routines in the catalog. Older data sets have smaller absolute numbers. The relative name 
is a signed integer used to refer to the latest (0), next to the latest (-1), etc. generation. 
The relative number can also be used to catalog a new generation (+1). 

In MVS, a generation data group base is created in a VSAM catalog before the 
generation data sets are cataloged. A generation data group is represented in the VSAM 
catalog by a generation data group base entry. The Access Method Services' DEFINE 
command is used to create the generation data group base. See OS/VS2 Access Method 
Services for information on how to define and/or catalog generation data sets. 



Absolute Generation and Version Numbers 



An absolute generation and version number is used to identify a specific generation of a 
generation data group. The generation and version numbers are in the form GxxxxVyy, 
where xxxx is an unsigned four-digit decimal generation number (0001-9999) and yy is 
an unsigned two-digit decimal version number (00-99). For example: 

• A.B.C.G0001V00 is generation data set one, version zero, in generation data group 
A.B.C. 
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• A.B.C.G0009V01 is generation data set nine, version one, in generation data group 
A.B.C. 

The number of generations and versions is limited by the number of digits in the absolute 
generation name, that is, 9999 for generations and 100 for versions. 

The generation number is automatically maintained by the system. The number of 
generations kept depends on the size of the generation index. For example, if the size of 
the generation index allows ten entries, the ten latest generations may be maintained in 
the generation data group. 

The version number allows you to perform normal data set operations without disrupting 
the management of the generation data group. For example, if you want to update the 
second generation in a three-generation group, replace generation two, version zero, with 
generation two, version one. Only one version is kept per generation. 

A generation can be cataloged using either absolute or relative numbers. When a 
generation is cataloged, a generation and version number is placed as a low level entry in 
the generation data group. In order to catalog a version number other than V00, you 
must use an absolute generation and version number. 

A new version of a specific generation can be cataloged automatically by specifying the 
old generation number along with a new version number. For example, if generation 
A.B.C.G0005V00 is cataloged in the index and you now create and catalog 
A.B.C.G0005V01, the new entry is cataloged in the index location previously occupied 
by A.B.C.G0005V00. This process removes the old entry from the catalog but does not 
scratch the old version. To scratch the old version and make its space available for 
reallocation, a DD card, describing the data set to be deleted, with 
DISP=(OLD,DELETE) should be included at the time the data set is to be replaced by 
the new version. 



Relative Generation Number 



As an alternative to using absolute generation and version numbers when cataloging or 
referring to a generation, you can use a relative generation number. To specify a relative 
number, use the generation data group name followed by a negative integer, a positive 
integer, or a zero, enclosed in parentheses. For example, A.B.C(-l). A.B.C(+1), or 
A.B.C(0). 

The value of the specified integer tells the operating system what generation number to 
assign to a new generation, or it tells the system the location (in the generation index) of 
an entry representing a previously cataloged generation. 

When you use a relative generation number to catalog a generation, the operating system 
assigns an absolute generation number and a version number of V00 to represent that 
generation. The absolute generation number assigned depends on the number last 
assigned and the value of the relative generation number that you are now specifying. 
For example if , in a previous job generation, A.B.C.G0005V00 was the last generation 
cataloged, and you specify A.B.C(+1), the generation now cataloged is assigned the 
number G0006V00. Though any positive relative generation number can be used, a 
number greater than 1 may cause absolute generation numbers to be skipped. For 
example, if you have a single-step job, and the generation being cataloged is a +2, one 
generation number is skipped. However, in a multiple-step job, one step may have a +1 
and a second step a +2, and no numbers are skipped in this case. 

Note: If you do not specify a volume in the JCL for a new generation data set, and the 
data set is not opened, that data set is not cataloged. 
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Progr amming Considerations for Multiple-Step Jobs 



One of the reasons for using generation data groups is to allow the system to maintain a 
given number of related cataloged data sets. If you attempt to delete or uncatalog any 
but the oldest of the data sets of a generation data group in a multiple-step job, catalog 
management can lose orientation within the data group. This can cause the deletion, 
uncataloging, or retrieval of the wrong data set when referring to a specified generation. 
The rule is, if you delete a generation data set in a multiple-step job, do not refer to any 
older generation in subsequent job steps. 

Also, it is recommended that in a multiple-step job, you catalog or uncatalog data sets 
using JCL instead of IEHPROGM or a user program. Since 

ALLOCATION/UNALLOCATION monitors data sets during job execution and is not 
aware of the functions performed by these programs, data set orientation may be lost or 
conflicting functions may be performed in subsequent job steps. 

When you use a relative generation number to refer to a generation that was cataloged in 
a previous job, the relative number has the following meaning: 

• A.B.C(O) refers to the latest existing cataloged entry. 

• A.B.C(-l) refers to the next-to-the-latest entry, etc. 

When cataloging is requested via JCL, all actual cataloging occurs at step termination, 
but the relative generation number remains the same throughout the job. Because this is 
so: 

• A relative number used in the JCL refers to the same generation throughout a job. 

• A job step that terminates abnormally may be deferred for a later step restart. If the 
step cataloged a generation data set via JCL, you must change all relative generation 
numbers in the succeeding steps via JCL before resubmitting the job. 

For example, if the succeeding steps contained the relative generation numbers: 

• A.B.C(+ 1), which refers to the entry cataloged in the terminated job step. 

• A.B.C(O), which refers to the next to the latest entry. 

• A.B.C(-l), which refers to the latest entry, prior to A.B.C(O). 

You must change them as follows before the step can be restarted: A.B.C(O), A.B.C(-l), 
A.B.C(-2), etc. 



Building a Generation Index in a CVOL 



A generation data group is managed via the information found in a generation index. 
(Note that an alias name cannot be assigned to the highest level of a generation index.) 
The BLDG function builds the index. The BLDG function also indicates how older or 
obsolete generations are to be handled when the index is full. For example, when the 
index is full, you may wish to empty it, scratch existing generations, and begin cataloging 
a new series of generations. 

After the index is built, a generation can be cataloged by its generation data group name 
and either an absolute generation and version number or a relative generation number. 

Examples on how to build a generation-data-group index are found in OS/VS Utilities. 



Creating a New Generation 



To create a new generation data set you must first allocate space for the generation, then 
catalog the generation. 
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step that builds the index or in any other job step that precedes the step in which you 
create and catalog your generation. 

//name DD DSNAME=datagrpname,DISP=( /KEEP ) ,SPACE=( TRK, ( ) ) , 
// UNIT=yyyy,VOLUME=SER=xxxxxx, 
// DCB=( applicable subparameters ) 
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The DSN AME is the common name by which each generation is identified; xxxxxx is 
the serial number of the volume containing the catalog. If no DCB subparameters are 
desired initially, you need not code the DCB parameter. 

2. You do not need to create a model DSCB if you can refer to a cataloged data set 
whose attributes are identical to those you desire or to an existing model DSCB for 
which you can supply overriding attributes. A cataloged data set referred to in this 
manner must reside on the same volume as your index. To refer to a cataloged data set 
for the use of its attributes, specify DCB=(dsname) on the DD statement that creates 
and catalogs your generation. To refer to an existing model, specify 
DCB=(modeldscbname, your attributes) on the DD statement that creates and 
catalogs your generation. 



A new generation may be passed when created. That generation may then be cataloged 
in a succeeding job step or deleted at the end of the job as in normal disposition 
processing when DISP=(,PASS) is specified on the DD statement. 

However, once a generation has been created with DISP=(NEW,PASS) specified on the 
DD statement, another new generation for that data group must not be cataloged until 
the passed version has been deleted or cataloged. To do so would cause the wrong 
generation to be used when referencing the passed generation data set. If that data set 
was later cataloged, a bad generation would be cataloged and a good one lost. 

For example, if A.B.C(+1) was created with DISP=(NEW,PASS) specified on the DD 
statement, then A.B.C.(+2) must not be created with DISP=(NEW,CATLG) until 
A.B.C(+1) has been cataloged or deleted. 

By using the proper JCL, the advantages to this support are: 

• JCL will not have to be changed in order to rerun the job. 

• The lowest generation version will not be deleted from the index until a valid version 
is cataloged. 



Creating an ISAM Data Set as Part of a Generation Data Group 



To create an indexed-sequential data set as part of a generation data group, you must: 

( 1 ) create the indexed-sequential data set separately from the generation group and 

(2) use IEHPROGM to put the indexed-sequential data set into the generation group. 

Use the RENAME function to rename the data set. Then use the CATLG function to 
catalog the data set. For instance, if MASTER is the name of the generation data group, 
and GggggVvv is the absolute generation name, you would code the following: 

RENAME DSNAME=ISAM,VOL=2314=SCRTCH,NEWNAME=MASTER.GggggVvv 
CATLG DSNAME=MASTER.GggggVvv, VOL=23 14=SCRTCH 



Retrieving a Generation 



A generation may be retrieved through the use of job control language procedures. Any 
operation that can be applied to a non-generation data set can be applied to a generation. 
For example, a generation can be updated and reentered in the catalog, or it can be 
copied, printed, punched, or used in the creation of new generation or non-generation 
data sets. 

You can retrieve a generation by using either relative generation numbers or absolute 
generation and version numbers. 
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Because two or more jobs can compete for the same resource, generation data groups 
should be updated with care, as follows: 

• No two jobs running concurrently should refer to the same generation data group. As 
a partial safeguard against this situation, use absolute generation and version numbers 
when cataloging or retrieving a generation in a multiprogramming environment. If you 
use relative numbers, a job running concurrently may update the generation data 
group index, perhaps cataloging a new generation which you will then retrieve in place 
of the one you wanted. 

• Even when using absolute generation and version numbers, a job running concurrently 
might catalog a new version of a generation or perhaps delete the generation you 
wished to retrieve. For this reason, some degree of control should be maintained over 
the execution of job steps referring to generation data groups. 



Controlling Confidential Data 

Password Protection for Non VSAM Data Sets 



Password protection as described here applies to non VSAM data sets only. For 
information on password protection for VSAM data sets, see OS/VS2 Access Method 
Services. 

In addition to the usual label protection that prevents opening of a data set without the 
correct data set name, the operating system provides data set security options that 
prevent unauthorized access to confidential data. Two levels of protection options are 
available. You specify these options in the LABEL field of a DD statement with the 
parameter PASSWORD or NOPWREAD. 

• Password protection (specified by the PASSWORD parameter) makes a data set 
unavailable for all types of processing until a correct password is entered by the 
system operator, or for a TSO job on MVS, the TSO user. 

• No-password-read protection (specified by the NOPWREAD parameter) makes a 
data set available for input without a password, but requires that the password be 
entered for output or delete operations. 

If an incorrect password is entered twice, the job is terminated by the system if it is being 
requested by the open or EOV routine. For a scratch or rename request, a return code is 
given. 

You can request password protection when you create the data set by using the LABEL 
field of the DD statement in your JCL. The system sets the data set security byte either 
in the standard header label 1 as shown in OS/VS Tape Labels or in the identifier data 
set control block (DSCB) as shown in OS/VS2 System Programming Library: 
Debugging Handbook. Once you have requested security protection for magnetic tapes, 
you cannot remove it with JCL unless you recreate the data set and scratch the protected 
data set. 

In addition to requesting password protection in your JCL, you must enter at least one 
record for each protected data set in a data set named PASSWORD that must be created 
on the system-residence volume. You should also request password protection for the 
PASSWORD data set itself to prevent both reading and writing without knowledge of 
the password. 

For a data set on a direct-access device, you can place the data set under protection at 
the same time that you enter its password in the PASSWORD data set. You can use the 
PROTECT macro instruction or the IEHPROGM utility program to add, change, or 
delete an entry in the PASSWORD data set; with either of these methods, the system 
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updates the DSCB of the data set to reflect its protected status. This provision eliminates 
the need for you to use JCL whenever you add, change, or remove security protection 
for a data set on a direct-access device. OS/VS2 System Programming Library: Data 
Management describes how to maintain the PASSWORD data set, including the 
PROTECT macro instruction; OS/VS2 MVS Utilities describes the ffiHPROGM utility 
program. 



RACF Protection for NonVSAM DASD Data Sets and 
Tape Volumes 



RACF (Resource Access Control Facility) protection as described here 
applies to nonVSAM data sets and tape volumes. For information on RACF 
protection for VSAM data sets, see OS/VS2 MVS Resource Access Control 
Facility (RACF): General Information Manual. 

RACF is a program product that provides for access control by identifying 
and verifying users and authorizing access to DASD data sets, and tape 
volumes with either standard or ANSI labels, which are defined to RACF. 

You may define a data set to RACF automatically or explicitly. The 
automatic definition occurs when space is allocated for the data set, if the user 
has the automatic data set protection attribute or if PROTECT=YES is 
coded on the DD statement. The explicit definition of a data set to RACF is 
by use of the RACF command language. 

A tape volume is defined to RACF explicitly by use of the RACF command 
language or automatically. This automatic definition occurs when the first 
data set on the first (or only) private volume is opened for OUTPUT or 
OUTIN and PROTECT=YES has been coded in the DD statement. RACF 
protection of tape data sets is provided on a volume basis and not on a data 
set basis. All data sets on a tape volume are RACF-protected if the volume is 
RACF-protected. 

There are five levels of access authority which you may have to a 
RACF-defined DASD data set or tape volume. 

ALTER 

You have total control over the data set. If you define the DASD data set 
or tape volume to RACF, you have ALTER access authority. With 
ALTER authority, you can read and write the data set or tape volume, 
rename the data set, and scratch the data set, and you may authorize other 
users access to the tape volume or data set. 

CONTROL 

For nonVSAM data sets, CONTROL authority is equivalent to UPDATE 
authority. 

UPDATE 

You are authorized to open the data set or tape volume for OUTPUT and 
all other open options. 

READ 

You are authorized to open the data set or tape volume for INPUT only. 

NONE 

You are not authorized to open the data set or tape volume. 
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If a DASD data set is both defined to RACF and password-protected, access 
to the data set is authorized only through RACF authorization checking. If a 
tape volume is defined to RACF and the data set(s) on the tape volume is 
password-protected, access to any of the data sets is authorized only through 
RACF authorization checking of the volume. Data set password protection is 
bypassed. 

To protect multivolume nonVSAM DASD and tape data sets, you must define 
each volume of the data set to RACF as part of the same volume set. When a 
RACF-protected data set is opened for output and extended to a new volume, 
the new volume will be automatically defined to RACF as part of the same 
volume set. When a multivolume physical sequentially organized data set is 
opened for output and the first volume opened is RACF-protected, each 
subsequent volume must either be | RACF-protected as part of the same volume 
set, or the data set must not yet exist on the volume. When a multivolume tape 
data set is opened for output and the first volume opened is RACF-protected, 
each subsequent volume must be either RACF-protected as part of the same 
volume set, or the tape volume must not yet be defined to RACF. If the first 
volume opened is not RACF-protected, no subsequent volume may be 
RACF-protected. If a multivolume data set is opened for input (or a 
nonphysical sequentially organized data set is opened for output), no such 
consistency check is performed when subsequent volumes are accessed. 
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Only standard label formats are used on direct-access volumes. Volume, data set, and 
optional user labels are used (see Figure 67). In the case of direct-access volumes, the 
data set label is the data set control block (DSCB). 



Cylinder 



Tracks 




VTOC 



All Remaining 
Tracks of Volume 



Unused Storage 
Area for Data Sets 



Figure 67. Direct-Access Labeling 



Volume-Label Group 



The volume-label group immediately follows the first two initial program loading (IPL) 
records on track of cylinder of the volume. It consists of the initial volume label at 
record 3 plus a maximum of seven additional volume labels. The initial volume label 
identifies a volume and its owner, and is used to verify that the correct volume is 
mounted. It can also be used to prevent use of the volume by unauthorized programs. 
The additional labels c#n be processed by an installation routine that is incorporated into 
the system. 

The format of the direct-access volume label group is shown in Figure 68. 
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Field 



8 i 



(Up to 7 Additional Volume Labels) 
80-Byte Physical Record 



(3) 



(1) 



(6) 



(1) 



( 5') 



(25) 



[10) 



(29) 



Volume Label Identifier (VOL) 
Volume Label Number (1) 

Volume Serial Number 

Volume Security 

VTOC Pointer 



Reserved (Blank) 



Owner Name and Address Code 



Blank 



Figure 68. Initial Volume Label 



Initial Volume Label Format 

The 80-byte initial volume label is preceded by a four-byte key containing VOL1. 

Volume Label Identifier (VOL): Field 1 identifies a volume label. 

Volume Label Number (1): Field 2 identifies the relative position of the volume label in a 
volume label group. It must be written as X'CT. 

The operating system identifies an initial volume label when, in reading the initial record, 
it finds that the first 4 characters of the record are VOL1. 

Volume Serial Number: Field 3 contains a unique identification code assigned when the 
volume enters the system. You can place the code on the external surface of the volume 
for visual identification. The code is normally numeric (000001-999999), but may be 
any 1 to 6 alphameric or national (#, $, @) characters, or a hyphen (X'60'). If this field 
is less than 6 characters, it is padded on the right with blanks. 

Volume Security: Field 4 is reserved for use by installations that wish to provide security 
for volumes. Make this field a CO' unless you have your own security processing 
routines. 

VTOC Pointer: Field 5 of direct-access volume label 1 contains the address of the 
VTOC in the form of CCHHR. 

Reserved: Field 6 is reserved for future developmental purposes. Le^ve it blank. 
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Owner Name and Address Code: Field 7 contains a unique identification of the owner of 
the volume. 

All the bytes in Field 8 are left blank. 



Data Set Control Block (DSCB) 



The system automatically constructs a DSCB when space is requested for a data set on a 
direct-access volume. Each data set on a direct-access volume has one or more DSCBs to 
describe its characteristics. The DSCB appears in the VTOC and contains 
operating-system data, device-dependent information, and data set characteristics, in 
addition to space allocation and other control information. There are seven kinds of 
DSCBs, each with a different purpose and a different format number. For an explanation 
of the seven kinds of DSCBs, see OS/VS2 System Programming Library: Debugging 
Handbook. 



User Label Groups 



User header and trailer label groups can be included with data sets of physically 
sequential or direct organization. The labels in each group have the format shown in 
Figure 69. 



Field 1 
2 




80-Byte Physical Record (Maximum of 8) 

Label Identifier (UHL if Header, UTL if Trailer) 
Label Number (1 -8) 



-^ User-Specified 



Figure 69. User Header and Trailer Labels 
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Each group can include up to eight labels, but the space required for both groups must 
not be more than 1 track on a direct-access device. The current minimum track size 
allows a maximum of eight labels, including both header and trailer labels. Consequently, 
a program becomes device-dependent (among direct-access devices) when it creates 
more than eight labels. 

If user labels are specified in the DD statement (LABEL=SUL), an additional track is 
normally allocated when the data set is created. No additional track is allocated when 
specific tracks are requested (SPACE=(ABSTR,...)), or when tracks allocated to 
another data set are requested (SUB ALLOC =...). In either case, labels are written on 
the first track that is allocated. 

User Header Label Group: The operating system writes these labels as directed by the 
processing program recording the data set. The first 4 characters of the user header label 
must be UHL1,..., UHL8; you can specify the remaining 76 characters. When the data 
set is read, the operating system makes the user header labels available to the problem 
program for processing. 

User Trailer Label Group: These labels are recorded (and processed) as explained in the 
preceding text for user header labels, except that the first 4 characters must be UTL1,...., 
UTL8. 



User Header and Trailer Label Format 



Label Identifier: Field 1 indicates the kind of user header label. UHL indicates a user 
header label; UTL indicates a user trailer label. 

Label Number: Field 2 identifies the relative position (1-8) of the label within the user 
label group. 

User-Specified: Field 3 (76 bytes). 
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Machine Code 



As an optional feature, each logical record, in any record format, may include a control 
character. This control character is recognized and processed if a data set is being written 
to a printer or punch. 

For format-F and format-U records, this character is the first byte of the logical record. 

For format-V records, it must be the fifth byte of the logical record, immediately 
following the record descriptor word. 

Two options are available. If either option is specified in the DCB, the character must 
appear in every record and other line spacing or stacker selection options also specified 
in the DCB are ignored. 



You can specify in the DCB that the machine code control character has been placed in 
each logical record. If the record is to be written, the appropriate byte must contain the 
command code bit configuration specifying both the write and the desired carriage or 
stacker select operation. 

The machine code control characters for a printer are as follows: 



Print and Then Act 


Action 


Act Immediately (No Printing) 


Code in Hexadecimal 


Code in Hexadecimal 


01 


Print only (no space) 




09 


Space 1 line 


OB 


11 


Space 2 lines 


13 


19 


Space 3 lines 


IB 


89 


Skip to channel 1 


8B 


91 


Skip to channel 2 


93 


99 


Skip to channel 3 


9B 


A1 


Skip to channel 4 


A3 


A9 


Skip to channel S 


AB 


B1 


Skip to channel 6 


B3 


B9 


Skip to channel 7 


BB 


CI 


Skip to channel 8 


C3 


C9 


Skip to channel 9 


CB 


D1 


Skip to channel 10 


D3 


D9 


Skip to channel 1 1 


DB 


El 


Skip to channel 12 


E3 
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The machine code control characters for a card read punch device are as follows: 



Code in Hexadecimal 


Action 


01 


Select stacker 1 


41 


Select stacker 2 


81 


Select stacker 3 



Other command codes for specific devices are contained in publications describing the 
control units and devices. 

Extended American National Standards Institute Code 

In place of machine code, you can specify control characters defined by the American 
National Standards Institute, Inc. (ANSI). Whenever IBM publications refer to ANSI 
code, they are as follows: 

Code Action Before Printing a Line 



b 


Space one line (blank code) 





Space two lines 


- 


Space three lines 


+ 


Suppress space 


1 


Skip to channel 1 


2 


Skip to channel 2 


3 


Skip to channel 3 


4 


Skip to channel 4 


5 


Skip to channel 5 


6 


Skip to channel 6 


7 


Skip to channel 7 


8 


Skip to channel 8 


9 


Skip to channel 9 


A 


Skip to channel 10 


B 


Skip to channel 1 1 


C 


Skip to channel 12 


Code 


Action After Punching a Card 


V 


Select punch pocket 1 


W 


Select punch pocket 2 



These control characters include those defined by ANSI FORTRAN. If any other 
character is specified, it is interpreted as 'b' or V, depending on whether it is for a printer 
or a punch; no error indication is returned. 
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GLOSSARY OF ACRONYMS AND 
ABBREVIATIONS 



The following terms are defined as they are used in this book. If you do not find the term 
you are looking for, refer to the index or to the IBM Data Processing Glossary, 
GC20-1699. 

A ANSI control code (value of RECFM) 

ABE abnormal end (value of EROPT) 

ABEND abnormal end (macro instruction) 

ABSTR absolute track (value of SPACE) 

ACC accept erroneous block (value of EROPT) 

AFF affinity (channel separation parameter of DD statement or unit affinity 

value of UNIT) 

AL American National Standard Labels 

ANSI American National Standards Institute 

ASCII American National Standard Code for Information Interchange 

AUL American National Standard User labels (value of LABEL) 

B blocked records (value of RECFM) 

BCDIC binary coded decimal interchange code 

BDAM basic direct access method 

BDW block descriptor word 

BFALN buffer alignment (operand of DCB) 

BFTEK buffer technique (operand of DCB) 

BISAM basic indexed sequential access method 

BLDL build list (macro instruction) 

BLKSIZE blocksize (operand of DCB) 

BPAM basic partitioned access method 

BPI bits per inch 

BSAM basic sequential access method 

BSM backspace past tapemark and forward space over tapemark (operand of 

CNTRL) 

BSP backspace one block (macro instruction) 

BSR backspace over a specified number of blocks (records) 

(operand of CNTRL) 

BUFCB buffer pool control block (operand of DCB) 

BUFL buffer length (operand of DCB) 

BUFNO buffer number (operand of DCB) 

BUFOFF buffer offset (length of ASCII block prefix by which the buffer 

is offset; operand of DCB) 

CCW channel command word 

CONTIG contiguous space allocation (value of SPACE) 

CNTRL control (macro instruction) 

CPU central processing unit 

CSW channel status word 

CYLOFL number of tracks for cylinder overflow records (operand of DCB) 

D format-D (ASCII variable-length) records (value of RECFM) 

DA direct-access (value of DEVD or DSORG) 

DAU direct-access unmovable data set (value of DSORG) 

DCB data control block (control block name or macro instruction) 

DCBD data control block dummy section macro instruction 

DD data definition 

DEB data extent block 
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DECB data event control block 

DEN magnetic tape density (operand of DCB) 

DEVD device-dependent (operand of DCB) 

DISP data set disposition (parameter of DD statement) 

DSCB data set control block 

DSORG data set organization (operand of DCB) 

EBCDIC extended binary coded decimal interchange code 

EODAD end-of-data set exit routine address (operand of DCB) 

EOF end-of-file 

EOV end-of-volume 

EROPT error options (operand of DCB) 

ESETL end sequential retrieval (QISAM macro instruction) 

EXCP execute channel program (macro instruction) 

EXLST exit list (operand of DCB) 

F fixed-length records (value of RECFM) 

FB fixed-length, blocked records (value of RECFM) 

FBS fixed-length, blocked, standard records (value of RECFM) 

FBT fixed-length, blocked records with track overflow option (value of 

RECFM) 

FCB forms control buffer 

FEOV force end-of-volume (macro instruction) 

FS fixed-length, standard records (value of RECFM) 

FSM forward space past tapemark and backspace over tapemark (operand of 

CNTRL) 

FSR forward space over a specified number of blocks (records) (operand of 

CNTRL) 

GCR group coded recording 

GL GET macro, locate mode (value of MACRF) 

GM GET macro, move mode (value of MACRF) 

HA home address 

I/O input/output 

INOUT input then output (operand of OPEN) 

IOB input/output block 

IPL initial program load 

IRG interrecord gap 

IS indexed sequential (value of DSORG) 

ISAM indexed sequential access method 

ISU indexed sequential unmovable (value of DSORG) 

JCL job control language 

JFCB job file control block 

JFCBE job file control block extension for 3800 printer 

KEYLEN key length (operand of DCB) 

LPA link pack area 

LPALIB link pack area library 

LRECL logical record length (operand of DCB) 

M machine control code (value of RECFM) 

MACRF macro instruction form (operand of DCB) 

MOD modify data set (value of DISP) 

MSHI main storage for highest-level index (operand of DCB) 

MSS Mass Storage System 
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MSVC Mass Storage Volume Control 

MSWA main storage for work area (operand of DCB) 

NCP number of channel programs (operand of DCB) 
NOPWREAD no password to read a data set (value of LABEL) 

NRZI non-return-to-zero-inverted (tape recording mode) 

NSL nonstandard label (value of LABEL) 

NTM number of tracks in cylinder index for each entry in lowest level of 
master index (operand of DCB) 

OMR optical mark read 

OPTCD optional services code (operand of DCB) 

OS/VS operating system/virtual storage 

OUTIN output then input (operand of OPEN) 

PCI program-controlled interruption 

PDAB parallel data access block 

PDS partitioned data set 

PE phase encoding (tape recording mode) 

PL PUT macro, locate mode (value of MACRF) 

PM PUT macro, move mode (value of MACRF) 

PO partitioned organization (value of DSORG) 

POU partitioned organization unmovable (value of DSORG) 

PRECL physical record length (field of DCB) 

PRTSP printer line spacing (operand of DCB) 

PS physical sequential (value of DSORG) 

PSU physical sequential unmovable (value of DSORG) 

QISAM queued indexed sequential access methods 

QSAM queued sequential access method 

RCE read column eliminate 

RDBACK read backward (operand of OPEN) 

RDW record descriptor word 

RECFM record format (operand of DCB) 

RKP relative key position (operand of DCB) 

RLSE release unused space (DD statement) 

RPS rotational position sensing 

S standard format records (value of RECFM) 

SDW segment descriptor word 

SEP separation (channel separation parameter of DD statement or 

unit separation value of UNIT) 

SER volume serial number (value of VOLUME) 

SETL set lower limit of sequential retrieval (QISAM macro instruction) 

SF sequential forward (operand of READ Or WRITE) 

SK skip to a printer channel (operand of CNTRL) 

SKP skip erroneous block (value of EROPT) 

SL IBM standard labels (value of LABEL) 

SMSI size of main-storage area for highest-level index (operand of DCB) 

SMSW size of main-storage work area (operand of DCB) 

SP space lines on a printer (operand of CNTRL) 

SS select stacker on card reader (operand of CNTRL) 

SUL IBM standard and user labels (value of LABEL) 

SVC supervisor call 

SVCLIB supervisor call library 

SYNAD synchronous error routine address (operand of DCB) 
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SYSIN system input stream 

SYSOUT system output stream 

T track overflow option (value of RECFM) 

TIOT task I/O table 

TRC table reference character 

TRTCH track recording technique (operand of DCB) 

U undefined length records (value of RECFM) 

UCS universal character set 

UHL user header label 

UTL user trailer label 

V format-V (variable-length) records (value of RECFM) 

VB variable-length, blocked records (value of RECFM) 

VBS variable-length, blocked, spanned records (value of RECFM) 

VS virtual storage or variable-length, spanned records 

VTOC volume table of contents 



166 OS/VS2 MVS Data Management Services Guide 



INDEX 



abbreviations 163-166 

ABE error option 40 

ABEND exit 49-53 

abnormal termination during open, close, EOV processing 

EST AE exit 56 

STAEexit 56 

STAIexit 56 
absolute actual address 33 

allocating space for data sets containing 136 

use with direct data sets 128 
absolute generation name 1 50 
ACC error option 40 
access method 18 

basic 62-65 

queued 18,59-62 

selecting 66,67 
Access Method Services 

DEFINE command 150 

program use of 1 50 
access techniques 

basic 18,62-65 

queued 18,59-62 
acronyms 163-166 
actual track address 

(MBBCCHHR) 33 

allocating space for data sets containing 136 
use with direct data sets 128,130 
use with feedback option 129 
address, direct-access storage device 

absolute actual 33 

allocating space for data set containing 136 
use with direct data sets 128 

direct 127 

indirect 127 

relative 33 

in directories 99-100 
use with direct data sets 128 
AFF affinity, channel 37 
alias entry in directory 

effect of changing directory entry 102 

specifying 98 
alignment 

buffer 75 

data control block 53 
allocation (see space allocation) 
American National Standard Code 

for Information Interchange 
(see ASCII block prefix; ASCII format) 
American National Standard labels 21 
American National Standard Institute (see ANSI control 

character; American National Standard labels) 
ANSI control character 

described 162 

device-type considerations 84 

used with chained scheduling 92-93 

with format-D records 28 

with format-F ASCII tape records 23 
anticipatory buffering 

omitted with basic access technique 62 

with queued access technique 59 



ASCII block prefix 

restriction 23,24,28 

with format-D records 28 

with format-F records 23-24 

with format-U records 30 
ASCII format 

restriction for 7-track tape 84 

translating data from 17,21,59,93 

translating data to 17,21,59,63 
ASCII tape 

buffer alignment 75 

fixed-length records 23 

undefined-length records 30 

variable-length records 28,29 
associated data set 

restriction with chained scheduling 92 
ATLAS macro 66 
automatic blocking/deblocking with queued 

access techniques 59 
automatic cataloging of data sets 19 
automatic error options (EROPT) operand of 

DCB macro 40 
automatic volume switching 59,72,74, 147 
auxiliary storage (see data set storage; direct-access storage; 
magnetic tape volumes) 

B 

backspace 

by BSP macro 89 

by CNTRL macro 87 
basic access technique 

(see also BDAM, BISAM, BPAM, and BSAM) 

blocking 62 

buffer acquisition and control 74-75,76,78,79 

deblocking 62 

definition of 62-65 

overlapped I/O 62 

using BDW 24 
BCDIC translation to EBCDIC 85 
BDAM (basic direct-access method) data set 

(see also basic access technique) 

access technique 127 

adding records 131-133 

CHECK macro 64 

creating 129-130 

dynamic buffering 79,127 

exclusive control for updating 128 

extended search option 128 

feedback option 129 

organization 127 

processing 127-133 
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READ macro 64 

record format 131 

restriction with chained scheduling 92 

selecting an access method 66,67 

sharing data set 55,56 

spanned variable-length records 25-28 

SYNAD routine 40 

updating records 131-133 

user labels 42,132 

WAIT macro 64,65 

when sharing a data set 55,56 

WRITE macro 63,64 
BDW (block descriptor word) 24 
BFTEK operand of DCB macro 

BFTEK=A 26,78 

BFTEK=R spanned records 63 
BISAM (basic indexed sequential access method) data set 

(see also indexed sequential data set) 

dynamic buffering 79 

retrieving 121-123 

sharing a DCB 56,123 

updating 121-125 

when sharing a data set 55,56 
BLDL macro instruction 

build list format 101 

coding example 105 

description 101 

updating a partitioned data set 105 
BLKSIZE operand of DCB macro 

description 36 

effect of data check on 22,84 

for writing a short block 96 

for card reader and punch 86 

for undefined-length records with QSAM 93 

including block prefix 29 

requirement for direct data set 127 

specifying 91,135,136 

when ignored 138,146 
block count exit routine 47-48 
block, data 21 

block descriptor word (BDW) 24 
block prefix (ASCII) records 

buffer alignment 75 

with format-D records 28-29 

with format-F records 23-24 

with format-U records 30 
block size field (see BLKSIZE field) 
blocking 

automatic 59 

defined 21 

with basic access technique 62 

with fixed-length records 22-24 

with spanned records 25-26 

with variable-length records 24-25 

with undefined-length records 30 
boundary alignment 

buffer 75 

data control block 53 
BPAM (basic partitioned access method) data set 

concatenation 147-148 

creating 103-104 

defined 18,97-98 

EODAD routine 38 

processing 97-107 



restriction with 

chained scheduling 105 

DCB ABEND exit routine 49 

fixed-length records, standard format 23 

search direct operation 93 
retrieving member 104,105 
space allocation for 138 
updating member 105,106 
when sharing a data set 55,56 
BSAM (basic sequential access method) data set 
as SYSIN/SYSOUT data sets 146 
creating 93,94 

creating a BDAM data set 129 
determining the length of a record 96 
EODAD routine 38,39 
extending 96 

how EODAD routine is entered 38 
overlap of I/O 62,92 
retrieving 94 

to update the directory 102 
updating 94-95 
user labels 42 
user totaling 45-46 
when sharing a data set 55,56 
writing a short block 96 
BSP macro instruction 
description 89 

restriction in EODAD routine 38 
BUFCB operand in DCB macro 75 
buffer 

(see also FREEBUF; FREEDBUF; GETBUF; RELSE) 
acquisiton and control 74-83 
alignment 75 
automatic for ISAM 79 

direct 75,79 

dynamic 75,79 
control 77-79 

for basic access technique 75,76 
length (BUFL operand of DCB macro) 75, 1 14 
number (BUFNO operand of DCB macro) 75,76,92 
pool 75-77 

(see also buffer pool) 
releasing 82 
segment 74,77 
truncating 83 
buffer pool 

(see also BUILD; GETPOOL; FREEPOOL) 

automatic construction 75,76 

building 75-76 

coding examples 77,78 

description 74-75 

explicit 75 

freeing 77 

getting 76 

getting a buffer from 83 

returning a buffer to 83 

returning a dynamic buffer to 83 

segment 74 

static 75 
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buffering 67 

anticipatory 

for queued access technique 59 
omitted for basic access technique 62 

direct control of 78 

dynamic 75 

exchange 75,82 

look-ahead 59 

simple 74,75,79-81 
BUFL operand in DCB macro 

for card punch 86 

for constructing a buffer pool 75 

for ISAM 114 

for printer 86 
BUFNO operand in DCB macro 

affecting chained scheduling 92 

affecting performance 92 

when constructing a buffer pool 75,76 

when ignored 146 
BUFOFF operand of DCB macro 

with format-DB records 93 

with QSAM or BSAM 23 

with variable-length records 28-29 
build list format 101 

(see also BLDL) 
BUILD macro instruction 

description 75 

with ISAM data set 114 
BUILDRCD macro instruction 

description 76 

restriction 27 

usage 26,27 



CAMLST macro, use of 150 
capacity for direct-access 

cylinder 20,137 

record 32,130,135 

track 137 
card punch, record format with 85 
card reader 

record format with 85 

relationship with CNTRL macro 87 

restriction with CNTRL macro 87 
carriage control characters 

defined 31,161,162 

specification of in RECFM field 84 
CATALOG macro, use of 150 
catalog, system 149 

control volumes 149 

entering a data set name 150 
cataloging data sets 

automatic 19 

defined 17 

for a generation data group 149-150 
CCW (see channel command word) 



chained scheduling 
description 83,92,93 
restriction with 
BDAM 92 

calculating record length 96 
CNTRL macro 92 

DOS checkpoint records, embedded on tape 92 
format-D records 29 
paper-tape reader 92 
partitioned data set 105 
SKP option 40 
spooled data sets 92 
track overflow 92 
UPD AT operand 92 
updating a sequential data set 94 
2540 Card Read Punch 93 
3525 Card Punch 92 
changing an address in the data control block 53,54 
channel command word (CCW) 
creation by OPEN 67 
PCI flag in 92 
use in simple buffering 79 
channel program 

execute (EXCP) 18,66 
number of (NCP) 62,92, 146 
channel separation and affinity field of DD statement 37 
character set, changing 88 
CHECK macro instruction 
description 64 
to enter EODAD routine 38 
to update a partitioned data set 105 
to update a sequential data set 94 
use with BDAM 56 
use with SYNAD routine 40,62 
using WAIT instead (see WAIT macro instruction) 
when sharing a data set 55,56 
with basic access technique 62 
check routine, examining DECB 65 
checkpoint/restart 

check of JFCBFLAG 47 
restriction for LPALIB 47 
CHKPT macro instruction 

use in end-of-volume exit routine 47 
CLOSE macro instruction 
description 70-72 
for multiple data sets 71 
for parallel input processing 60-62 
in EODAD routine 38 
restriction with SYNAD 39,70 
temporary close option 70-72 
TYPE=T 70-72 
volume positioning 68,70,71,72 
with partitioned data set 102-104 
with STOW macro 102 
closing a data set 67-72 
CNTRL macro instruction 
device dependence 87 
restrictions 

with BSP macro instruction 89 
with chained scheduling 92 
with DOS checkpoint records 
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concatenation 

defined 147 

of data sets on RPS devices 148 

of partitioned data sets 1 47- 1 48 

of sequential data sets 147,148 

of unlike data sets 147 

restriction with partitioned data sets 10S 
control buffer (see forms control buffer) 
control character 

(see also CNTRL, PRTOV) 

ANSI 23,28,84,92 

carriage 22,25,31,161,162 

code 161,162 

explained 31 

format-D 28 

format-F 23 

format-U 30 

format-V 25 

machine 84,93,161,162 

specifying 84,161,162 

with fixed-length records 23 

with undefined-length records 30 

with variable-length records 25 
control section, dummy (DSECT) 53 
control volume 149 
count area 32 

count-data format 32 

count-key-data format 32 

in device overhead 136 

in ISAM index entry format 109 
CRE ATE V command, use of 135 
cross reference table with direct data sets 127 
CSECT statement, use of with DCBD macro 53 
cylinder 

allocation by 1 36 

capacity 20,137 

index 

calculating space requirements for 138-1 39 
definition 107,109 

overflow 

calculating space for 139,141 
defined 107,110 
specifying size 

via CYLOFL parameter 139 
CYLOFL (cylinder overflow) operand of DCB macro 
when allocating ISAM data set 139 
when creating ISAM data set 119 

D 

D-format records (see format-D records) 
data access techniques (see access techniques) 
data check 

effect on BLKSIZE 22,84 
with SETPRT macro 88 
data control block (DCB) 
ABEND exit 

description 49-51 
when available 38 
where specified 38 
attributes of, determining 35-37,53 
changing an address in 53,54 
creation by DCB macro instruction 19,34 
description 34-35 
dummy control section 53 
exit 

description 46 



when available 38 

when used by SYSIN/SYSOUT 146 

where specified 38 
fields 35-37 
initial setting of 54 
modifying 34,53-54 
operand of DD statement 37 
primary sources of information 35 
sequence of completion 36 
use 19 

when sharing a data set 54 
data definition name (ddname) field of DD statement 37 
data definition (DD) statement 
fields 37 

relationship to DCB 35 
relationship to JFCB 35 
use 19 
data errors 40-41 

(see also SYNAD routine) 
data event control block (DECB) 
description of 65 
use of 95 
data management, introduction to 17-57 
data mode processing 

relationship with buffers 78 
data set 

characteristics 17-30 
description 35-37 
disposition (DISP) operand 

cataloging 145 

description 37 

overridden by OPEN macro 73 
identification 19 
label (DSCB) 19,20,157-160 

(see also magnetic tape volumes; data set control 
block; labels, direct-access) 
label (LABEL) field of DD statement 37 
like characteristics 147 
name 19 

name (DSNAME) field 37 
organization 18 

(see also BDAM, BISAM, BPAM, BSAM, QISAM, 
and QSAM data sets) 
organization (DSORG) operand of DCB macro 36 
record formats 21-30 

routing through the input/output stream 145-147 
security 17,154 
sharing 
space allocation on direct-access volumes 1 3 5- 1 45 

estimation 136-138 

for a direct data set 127 

for indexed sequential data sets 138-145 

for MSS volume 136 

for partitioned data sets 1 3 8 

specifying 135-136 
storage 19-21 

direct-access 20 

magnetic-tape 20-21 
SYSIN 145-147 
SYSOUT 145-147 
unlike characteristics 147 
unmovable 

direct organization 127 

resulting from use of MMBBCCHHR 33 

specification in DSORG operand of DCB 36 

(see also BDAM, BISAM, BPAM, BSAM, QISAM, 
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and QSAM data sets) 
data set control block (see DSCB) 
DCB (see data control block) 
DCB ABEND exit 49-51 
DCB macro instruction 34-35 

(see also data control block) 
DCBBLKSI field in DCB 86,87,96 
DCBD macro instruction 

restriction on use 53 

use 53,54 
DCBLPDA field of DCB 118 
DCBLRECL field of DCB 96 
DCBNCRHI field of DCB 1 17 
DCBPRECL field of DCB 25 
DCBSYNAD field of DCB 54 
DD statement fields 35-37 
DDNAME (see data definition name field) 
deblocking, automatic 59 
DECB (see data event control block) 
defer nonstandard input trailer label exit 48 
DEFINE command, use of 1 50 
defining an FCB image 48 
delete option 

restriction when updating a sequential data set 95 

restriction with RKP 113 

use with SETL 118 
deletion 

of indexed sequential data set records 112-113 

of member name using STOW macro 102 
DEN (tape density) 84-85 
density, tape 84-85 
DEQ macro, use of 55,56,123 
descriptor word (see block descriptor word; record descriptor 

word; segment descriptor word) 
determinate errors 68 
DEVD operand of DCB 

device-class independence considerations 91 

restriction with SYSOUT data sets 146 

specifying 84 

withBDAM 129 

with SYSOUT data sets 
device control for sequential data sets 87-89 
device-dependent macro instructions 87-89 
device independence 90-92 
device-type considerations for data format 

sequential organization 83-87 
DEVTYPE macro, use of 116 
direct-access device characteristics 3 1-34 
direct-access volume 20 

access mechanism 31 

device characteristics 31-34 

devices (see 2305 Fixed Head Storage; 2314 Direct Access 
Storage Facility; 2319 Disk Storage; 3330 Disk Drive; 
3333 Disk Storage; 3340 Disk Storage; 3350 Disk 
Storage) 

labels 19 

record format 21-30,84,87 

track, defined 3 1 

track addressing 33 

track format 32 

track overflow 34 

write validity check 34 
direct addressing 127 
direct data set (see BDAM data set) 
direct organization (see BDAM data set) 
directory (see BPAM data set) 
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disk drive (see 2305 Fixed Head Storage; 2314 Direct Access 
Storage Facility; 2319 Disk Storage; 3330 Disk Drive; 
3333 Disk Storage; 3340 Disk Storage; 3350 Disk 
Storage) 
Disk Operating System (see DOS tapes with embedded 

checkpoint records) 
DISP operand 

description 37,73 

for extending sequential data set 96 

for indexed sequential data set 112 

for partitioned data set 102,103 

for tape 35,44 

specifying 145 

when DISP=SHR for sharing data sets 55, 123 

when passing a generation 153 

when updating the directory 102 
DOS (Disk Operating System) tapes with embedded 
checkpoint records 

restriction with BSP 89 

restriction with chained scheduling 92 

restriction with CNTRL 88 

restriction with POINT 89 
drum storage (see 2305 Fixed Head Storage) 
DSCB 

contents of 157-160 

data set label 157-160 

data set security byte 1 54 

described 19,20,159 

index (f ormat-2) HIRPD field of 116 
DSECT statement 53 

DSNAME operand of DD statement 37 , 1 02, 1 05 
DSORG operand of DCB macro 

described 36 

for direct data set 129 

for sequential data set 93,94 

with CLOSE TYPE=T 71 

with indexed sequential data set 119 

with partitioned data set 1 02, 1 03 , 1 04 
dummy control section for DCB 53,54 
dummy data set, restriction with parallel input processing 60 
dummy record 

with direct data set 1 30, 1 3 1 
dynamic buffering 

buffer control 75,127 

for direct data set 127 

for ISAM data set 119,121 

release of using FREEDBUF 83 

(see also READ; RELEX; WRITE) 

specifying 75 

E 

EBCDIC (extended binary coded decimal interchange code) 

translation to and from ASCII 17,21,59,63,93 
for magnetic-tape volumes 21 
record-format dependencies 21-22 
embedded index area 1 39, 1 40 
end-of-data indicator 72 
end-of-data routine (EODAD) 38-39 

changing address of in DCB 53-54 

register contents 39 

with basic access technique 62 

with BSP macro 89 

with concatenated data sets 147-148 

with GET macro 59 

with queued access technique 59 
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end-of-volume 

exit routine 47 

forcing 74 

processing 72-73 

routines, relationship with DCB ABEND exit 49,51 

when EODAD routine entered 38-39 
ENQ macro, use of 

when sharing a data set 55,56, 123 
EODAD routine 38-39 

changing address of in DCB 53-54 

register contents 39 

with basic access technique 62 

with BSP macro 89 

with concatenated data sets 147-148 

with GET macro 59 

with queued access technique 59 
EROPT operand of DCB macro 40 
error 

analysis routine (SYNAD) 39-41 

determinate 68 

handling 65 

indeterminate 68 

options, automatic 40 

uncorrectable 39 
error routine {see SYNAD routine) 
ESETL macro instruction 

description 118 

in EODAD routine 39 

when sharing a data set 56 
ESTAE exit, abnormal termination 56 
exceptional condition code {see condition, exceptional) 
exchange buffering 82 
exclusive control 

updating direct data sets 128 

when sharing direct data sets 56 
EXCP macro instruction 66 
execute channel program (EXCP) 18 
exit list 41-42 
exit routine 

block count 47-48 

conventions 41-42 

data control block (DCB) 46 

DCB ABEND 49-53 

defer nonstandard input trailer label 48 

end-of-data 38-39 

end-of-volume 47 

FCB image 48 

JFCBE 47 

list 41-42 

QSAM parallel input 46 

register contents on entry 41 

standard user label 42-45 

synchronous error (SYNAD) 39-41 

user totaling 45-46 
exit routines identified by DCB 38 
EXLST operand of DCB macro 41 
EXTEND option, OPEN macro (VS2.03.808) 

device independence 91 

extending sequential data set 96 

indexed sequential data set 112 

QISAMuse 69 

specifying 35 

use with SYSIN/SYSOUT 69 



extended binary coded decimal interchange code (EBCDIC) 
translation to and from ASCII 17,21,59,63,93 
for magnetic-tape volumes 21 
record-format dependencies 21-22 
extended American National Standards Institute 
(ANSI) code 162 
{see also ANSI control character) 
extended search option for direct data sets 128 



F-format records {see f ormat-F records) 
FCB image 

exit 48 

identification in JFCBE 47 

relationship with SETPRT 88 
feedback 

option 129 

with BDAM READ macro 63 

with BDAM WRITE macro 64 
FEOV macro instruction 

description 76 

ignored for SYSIN/SYSOUT data sets 74 

restriction with spanned records 26,74 

restriction with trailer label exit 44 

to enter EODAD routine 38 
file mark, restriction 89 
FIND macro instruction 

description 101-102 

in EODAD routine 39 

updating a partitioned data set 105 

when sharing a data set 56 
fixed-length records 22-24 

with parallel input processing 60 
force end-of-volume {see FEOV macro instruction) 74 
format-D records 28-29 

restriction with chained scheduling 29 
f ormat-F records 22-24 

ASCII tapes 23-24 

standard format 22-23 

with card reader and punch 85 

with parallel input processing 60 
format-FBS records, restriction with search direct 93 
format-FBT records, restriction with search direct 93 
f ormat-FS records, restriction with search direct 93 
format-U records 30 

calculating record length 96 

restriction with chained scheduling 92 

with card reader and punch 85 

with parallel input processing 60 
format-UT records, restriction with search direct 93 
format-V records 24-29 

block descriptor word 24 

record descriptor word 25 

segment descriptor word 26 

segment control codes 26 

spanned 25-27 

with card punch 85 

with parallel input processing 60 
- with user totaling 46 
forms control buffer 

image exit list 48 
FREE operand 72 
FREEBUF macro instruction 

description 83 

to control buffers 75 
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FREEDBUF macro instruction 

description 83 

example 124 

for ISAM 122 

when sharing data sets 56 
FREEPOOL macro instruction 77 

when issued for card punch data set 86 

when issued for printer data set 87 
full track-index write option 1 19 



generation 

data set 150 

index 150 

numbers, relative 150-152 
generation data groups 

absolute generation name 150 

building an index 152 

creating a new 152 

defined 20,150 

entering in the catalog 1 50, 1 5 1 

relative generation name 150 

retrieving 
GET macro instruction 

description 59 

in EODAD routine 38,39 

restriction with spanned records 

to enter EODAD routine 38 

updating a sequential data set 

when sharing a data set 55 

with format-U records 30 

with parallel input processing 60,61 
GETBUF macro instruction 

description 83 

to control buffers 
GETPOOL macro instruction 

description 76 

with ISAM data set 114 
glossary 163-166 
grouping related control blocks 



94,95 



62 



H 



header label, user 42-45 , 1 59, 1 60 



IBCDASDI utility program 

restriction 135 
IDCAMS, MSS utility program 

use of 136 
IEBCOPY utility program 

use of 106,107 
IEHATLAS utility program 

use of 66 
IEHD ASDR utility program 

restriction 135 
IEHLIST utility program 

use of 117,140 
IEHMOVE utility program 

use of 99,100 
IEHPROGM utility program 

use of 140,153 
IHADCB macro instruction label 54 



independent overflow area 

description 110 

specifying 141 
indeterminate errors 68 
index 

area 107 

calculating space for 138-139 

catalog 19-20 

cylinder 109,121 

calculating space for 138,139 

master 109,110 

calculating space for 138,139 

track 108,109,121 

calculating space for 139 
indexed sequential data set 

(see also BISAM and QISAM) 

adding records 110-112 
inserting new records 1 10 
new records at the end 111,112 

areas 107-110 

allocating space for 114-117, 13 8-1 45 
prime 108 
index 108-110 
overflow 110 

buffer requirements 114-117 

creation 119-121 

deleting records 112,113 

device control 117-118 

full track-index write option 119 

retrieving 121-123 

SYNAD routine 41 

updating 121-126 
indexes of the catalog 19-20 
indirect addressing 127 
INOUT option 

OPEN macro 69 

opening magnetic tape volume 35 

when using POINT macro 89 
INPUT option 

OPEN macro instruction 69 

opening magnetic tape volume 35 
input/output device generation 90 
input/output devices for use with sequential data sets 

card reader and punch 85-86 

direct access 87 

magnetic tape 84 

paper tape reader 85 

printer 86 
input/output errors, recovering from 66 
interrecord gaps (IRGs) 21 

IOB, relationship with SYNAD routine for BDAM 40 
IRG (interrecord gap) 21 
ISAM (see indexed sequential data set; BISAM; QISAM) 



JES (job entry subsystem) 145-147 

JFCB (job file control block) 35,68 

JFCBE (job file control block extension) exit 47 

JFCBFLAG 47 

job file control block (JFCB) 35,68 

job file control block extension (JFCBE) exit 47 
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K 

key 

class 117 

for direct-access devices 32 

for indexed sequential data sets 107-109 

protection 107,147 

relative key position (RKP) for indexed sequential data 

set 113,114,119 
use of when adding records to indexed sequential data 

set 110-112 
use of when maintaining an indexed sequential data 

set 112 
use of when retrieving records from an indexed sequential 
data set 121-124 
KEYLEN operand of DCB macro 
description 36 
for direct-access device 87 
for direct data set 129 
KN see WRITE KN) 
KU {see READ KU) 



label exits 42-45 

labels, data set 19-20,35,37 

{see also magnetic-tape volumes; labels, direct-access) 
labels, direct-access 

data set control block 1 57- 1 60 

format 157-160 

user label groups 159,160 

volume label group 157-159 
LABEL parameter of DD statement 

description 37 

specifying password protection 154 

specifying standard labels 44 
LEAVE option 

for close processing 70,71 

for concatendated data sets 147 

for end-of-volume processing 73,74 

for forced end-of-volume processing 74 
length checking 22 
link field 114,115 

link pack area library, restriction for checkpoint 47 
load mode for QISAM 

in SYNAD routine 41 

when sharing a DCB 56 
load mode for BDAM when sharing data sets 56 
loading an indexed sequential data set 119 
locate mode processing 

defined for buffering 78 

example with simple buffering 80,81 

relationship with buffers 78 

to process records that exceed 32,760 bytes 27 

to update a member with QSAM 106 

with GET macro instruction 

creating a sequential data set, coding example 94,95 
simple buffering 79-81,94,95 

with parallel input processing 60 

with PUT macro instruction 

creating a sequential data set, coding example 95 
simple buffering 79-81,94,95 
look-ahead buffering 59 
LPALIB, restriction for checkpoint 47 



LRECL operand of DCB macro 
described 36 
device dependence 91 

restriction when calculating record length 96 
to process records that exceed 32,760 bytes 27 
with BDAM 129 
with BSAM 96 
with ISAM 

buffer requirements 116,117 

data set creation 119 
with PUT macro 59,60 
with SYSOUT data set 146 

M 

machine code control character 84,93,161,162 
MACRF (macro instruction form) operand of DCB macro 
described 37 
device independence 91 
dynamic buffering 123 
for BDAM 129 
processing mode 78 
relationship with WAIT macro 64,67 
to update a member using QSAM 106 
when sharing a data set 55,56 
magnetic-tape volumes 
defined 20-21 
density 84-85 
labels 

American National Standard 20,21 
none 20 
nonstandard 20 
standard 20 
user 42-45 
organization 20-21 
positioning 20 

during close processing 70-72 
during end-of-volume processing 72,73,74 
record format 21-31,84 
serial number 20-21 
tapemarks 21 
master catalog 149 
master index 109,110 
MBBCCHHR {see actual address) 
modes, processing {see data mode; locate mode; move mode; 

substitute mode) 
modifying the data control block 35,53-54 
move mode processing 

relationship with buffers 78 

use instead of exchange buffering 82 

with GET macro instruction 

creating a sequential data set 93 
simple buffering 79.80,94 
with parallel input processing 60 
with PUT macro instruction 

creating a sequential data set 94 
simple buffering 79-81,94 
MSS staging 107 

MSVGP parameter on JCL statemnt 136 
MSWA operand of the DCB macro 117 
multiple data sets 
closing 68 
opening 68 

processing for QISAM 75 
multitasking mode, sharing data sets 56,68 
multivolume data set 
with NOTE macro 89 
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names 

data set 19 

generation data group 20, 150,151 
NCP (number of channel programs) operand of the DCB 

macro 62,92,146 
nonstandard tape labels 20 
note list 100 
NOTE macro instruction 
description 89 
restriction with 
BSP macro 89 
multivolume data sets 89 
search direct operation 93 
updating a sequential data set 94 
use with partitioned data set 
updating 105 
NTM operand 110 
null segment 27 

o 

offset reading 63 

OMR (see optical mark read) 

OPEN macro instruction 

considerations for 68 

description 69-70 

for parallel input processing 60-62 

for simultaneous opening of multiple data sets 68 

for updating a sequential data set 94 

functions 35,69-70 

restriction with search direct 93 

used for more than one data set 68 

volume positioning for EOV 73 
opening a data set 67-70 
OPTCD operand of the DCB macro 

device dependence 92 

with ASCII tapes (OPTCD=Q) 59 

withBDAM 129 

with ISAM 119 

request user totaling (OPTCD=T) 45 
OPTCD=H 

embedded checkpoints, DOS tapes 88 

MSS staging 107 
OPTCD=M (master index) 110 
OPTCD =T (user totaling) 45 
OPTCD=Z (search direct option) 93 
OUTIN option 

OPEN macro 69 

when opening data set 35 

when using POINT macro 89 
OUTINX option, OPEN macro (VS2.03.808)35,69,91 
output mode 

defined 78 
OUTPUT option 

OPEN macro 69 

when opening data set 35 

when using POINT macro 89 
output stream 145-147 
overflow 

area 107,110 

chain 110 



Page of GC26-3875-0 
Revised June 29, 1979 
By TNL GN26-0944 

cylinder (see cylinder overflow) 

independent area 1 10 

PROTV macro 88 

records 110 

track 

description 34 

effect on chained scheduling 92 
restriction on BSP macro instruction 89 
restriction with parallel input processing 60 
restriction with RPS feature 96 
overlap of input/output 

performance improvement 92 

with basic access technique 62 

with partitioned data sets 106 

with sequential data sets 95 

with queued access technique 59 



paging environment, related control block group 62 
paper-tape reader 

described 85 

effect on chained scheduling 92 

record format with 85 

with a SYNAD routine 40 
parallel 

data access block (PDAB) 46,60,61 

input processing 46,60-62 
parameter list 

contents of 50 

use of by DCB ABEND exit routine 50-5 1 
partitioned data set (see BPAM data set) 
PASSWORD data set 154 
password protection 154 
PC (card punch) record format 85 
PCI flag 92 
PDABDDSECT 61 

PDAB (parallel data access block) 46,60,61 
PDS (see BPAM data set) 
performance improvement 92 
POINT macro instruction 

description 89 

in EODAD routine 39 

restriction with 
BSP macro 89 
multivolume data sets 89 
search direct operation 93 

updating a partitioned data set 105 

updating a sequential data set 94 
prefix, block (see block prefix) 
prefix, key 117 
prime data area 

description 107,108 

space allocation for 138,140,141 
printer 

overflow (PRTOV macro) 88 

record format with 86 

restriction with chained scheduling 92 
program, describing the processing 37-53 
PRTOV macro instruction 

description 88 

device dependent 91 

when macro will not function 88 
PT (see paper-tape reader) 
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PUT macro instruction 
description 59-60 
locate mode 78-81 
used to create a sequential data set, coding 

example 94,95 
with format-U records 30 
with indexed sequential data set 1 10-1 12 
with simple buffering 79-81 
with spanned records 27 

{see also data mode processing; locate mode 
processing; move mode processing; substitite mode 
processing) 
PUTX macro instruction 
description 60 
device independence 91 
forQISAM 129 
UPDATmode 81 
updating a sequential data set 94,95 
when sharing a data set 55 
with format-U records 30 
with simple buffering 79-81 
with spanned records 27 

{see also output mode; update mode) 



QISAM data set 

{see also indexed sequential data set) 

EODAD routine 39 

scan mode 123 

sharing 55,56 

SYNAD routine 40-41 

using common buffer pool 76 
QSAM 

{see also queued access technique) 

creating a BDAM data set 129 

parallel input processing 60-62 

performance improvement 92 

restriction with 

spanned records 26 

spanned variable-length records 25-27 

SYSIN/SYSOUT data sets 146 

to update a directory 102 

to update a member 106 

user labels 42 

user totaling 45-46 

when sharing a data set 55,56 

with card punch 86 

with printer 86 
queued access technique 

buffer control 74,76 

defined 59 

introduced 18 

processing modes {see data mode processing; locate mode 
processing; move mode processing; substitute mode 
processing) 
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RACF protection (VS2.03.808) 

RD (card reader) 85-86 

RDBACK option 45 

opening magnetic tape volume 35 
restriction for variable-length records 69 
restriction with SYSIN/SYSOUT data sets 

RDW {see record descriptor word) 

read backward (SB operand of READ macro) 



READ macro instruction 

description 63 

device independence 91 

in SYNAD routine 40 

restriction in EODAD routine 38 

supplying record length 96 

to enter EODAD routine 38 

to update existing records 122 

updating a partitioned data set 105 

updating a sequential data set 94,95 

when sharing a data set 55,56 

with basic access technique 62 

with format-U records 30 

with KU (key, update) 
in coding example 124 
RECFM operand of DCB macro 

description 36 

for sequential data sets 84 

selecting 21-23 

with card punch 85,86 

with card reader 85,86 

with control character 84 

with direct-access storage device 87 

with magnetic tape 84-85 

with paper tape reader 85 

with printer 86 

with sequential organization 84 
record blocking {see blocking) 
record descriptor word (RDW) 25 

data mode exception for spanned records 25 

variable-length records format-D 27,28,29 

when replaced by segment descriptor word 27 
record format 21-30 

fixed-length 22-24 

fixed-length for ASCII 23-24 

fixed-length standard 23 

spanned variable-length 25-27 

undefined-length 30 

variable-length 24-29 
record length (LRECL) operand of the DCB macro 36,91 
relative block address 

defined 33 

with direct data set 128 

with feedback option 129 
relative generation name 150-152 

relative key" position operand of the DCB macro 1 1 3, 1 14, 1 19 
relative track address 

defined 33 

with direct access 128 

with feedback option 129 
releasing data sets and volumes 72 
RELEX macro instruction 

exclusive control 56 

when sharing data sets 56 
RELSE macro instruction 

defined 82 

to terminate buffer processing 74 
reorganization of indexed sequential data set 112 
REREAD option 73,74 
restart end-of-volume exit routine 47 



69 



63 
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restrictions 

on ASCII records 

block prefix 23,24,28,29 
on 7-track tape 84 
on chained scheduling with 
BDAM 92 

calculating record length 96 
CNTRL macro 92 
DOS checkpoint records 92 
format-D records 29 
paper-tape reader 92 
partitioned data set 105 
SKP option 40 
spooled data sets 92 
track overflow 92,96 
UPD AT operand 92 
updating a sequential data set 94,95 
2540 Card Read Punch 93 
3525 Card Punch 92 
- on CNTRL macro 

with BSP macro 89 
with chained scheduling 92 
with DOS checkpoint records 88 
on DCB usage 68-69 
on DCBD macro usage 53,54 
on DOS checkpoint records 88-89,92 
on format-D records with chained scheduling 29 
on high-level index in storage 117 
on NOTE macro with 
BSP macro 89 
multivolume data sets 89 
search direct operation 93 
on POINT macro with 
BSP macro 89 
multivolume data sets 89 
search direct operation 93 
on reading concatenated data sets backward 147 
on user label exit routines 42-45 
with search direct 93 
resume load 1 1 2, 1 1 9, 1 20, 1 2 1 
retrieving a generation 153 
return code 

with block count exit 48 
with user labels 44 
RETURN macro 

relationship in SYNAD routine 39 
REWIND option 

for CLOSE macro 70 
for FEOV macro 74 
RKP (relative key position 113,114,119 
RLSE parameter of DD statement 70 
RORG1, RORG2, RORG3 fields of the DCB 1 12 
routing data sets through the input/output stream 145-147 
RPS (rotational position sensing) feature 

concatenating data sets on nonRPS devices 148 
restriction with track overflow records 
variable-length records 24 
when calculating record length 96 
R0 record 32,130,135 



save area, user totaling 45-46 
scan mode for QISAM 

in SYNAD routine 41 

issuing PUTX 123 
scheduling of input/output streams 145 
SDW (see segment descriptor word) 
search direct for input 93 
search option, extended 128 
secondary storage (see data set storage; direct-access storage; 

magnetic-tape volumes) 
security, data set 17,154 
segment 

buffer 74,77 

control code 26 

descriptor word 

for spanned records 26-27 
indicating a null segment 27 

null 27 
selecting an access method 66-67 
SEP (separation, channel) 37 
sequential data set 

(see also BPAM, BSAM, and QSAM data sets) 

creation 93-94 

concatenation 147-148 

extending 96 

retrieving 94 

updating 94-95 
sequential organization 

defined 18 

device control 87-89 

device independence 90-92 
SETL macro instruction 117-118 

in EOD AD routine 39 

when sharing a data set 56 
SETPRT macro instruction 88 
SETPRT routine 48 
sharing data sets 54-57 
sharing DASDs 
simple buffering 

description 79-81 

with parallel input processing 60,61 
SKP error option 40 
SMSI operand of the DCB macro 117 
SMSW operand of the DCB macro 1 16, 1 17 
Sort/merge program 

record restriction 22 
space allocation 

estimating requirements 136-138 

for a direct data set 127 

for an indexed sequential data set 138-145 

for an MSS volume 136 

for a partitioned data set 138 

specifying 135-136 
SPACE parameter 37 
spanned records 

basic direct access method 27 

considerations for 26-27 

restriction with parallel input processing 60 

restriction with search direct 98 

restriction with SYSIN data sets 27, 147 

sequential access method 25 

variable-length 25 
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spooling of SYSIN and SYSOUT data sets 145-147 

restriction 92 
stacker selection 

control characters for 22,3 1 , 162 

STACK operand 86 

using CNTRL macro 87 
STAEexit 56 
ST AI exit 56 

standard format for fixed-length records 23 
standard labels 

direct-access volumes 20,157 

magnetic-tape volumes 20,21 
storage (see direct-access storage; magnetic-tape volumes) 
STOW macro instruction 

description 102 

restriction with DCB ABEND exit 49 

when sharing a data set 56 
subpool 0, when shared 56 
substitute mode processing 78 

defined for buffering 78 
switching, volume 

automatic 

with end-of-volume 72 

with FEOV macro 74 

with GET macro 59 

restriction with concatenated data sets 147 

initiated by CHECK 64 
SYNAD field 

programming consideration 92 
SYNAD routine 

changing address in DCB 53 

description 39-41 

macros used in 65,66 

programming consideration 92 

relationship with SETL option 118 

relationship with DECB 65 

relationship with SYSIN/SYSOUT data sets 1 47 

temporary close restriction 70 

when adding records to ISAM data set 112 

when sharing a data set 56 

with basic access technique 62 

with queued access technique 59 
SYNAD AF macro instruction 

description 65 

examples 94,95 

use in SYNAD routine 39,40 
SYNADRLS macro instruction 

description 66 

examples 94,95 

use in SYNAD routine 40 
synchronous error routine exit (see SYNAD routine) 
SYSIN data set 

FEOV macro ignored for 74 

restriction with 

chained scheduling 92 
parallel input processing 60 
spanned variable-length records 27 
user totaling 45 

routing data through input stream 145-147 



SYSOUT data set 

FEOV macro ignored for 74 
restriction with 

chained scheduling 92 
label exits 44 

spanned variable-length records 27 
user totaling 45 
routing data through output stream 145-147 
system generation device independence 

considerations 90 
system input stream 1 45- 1 47 
system output stream 145-147 
system output writer 145-147 
SYS1, IMAGELIB 

fetching images from 88 
search of 48 
SYS1.LPALIB and checkpoint/restart 47 



table reference character (3800) (VS2.03.810) 22,25,31 

tape (see magnetic-tape volumes; paper-tape reader) 

tapemark 21 

temporary close 70-71 

totaling area, user totaling exit routine 45-46 

track 

addressing 33 
defined 31 
format 

count-data format 32 
count-key-data format 32 
index 107-109,121 
overflow option 
description 34 

effect on chained scheduling 92 
restriction of BSP macro instruction 89 
restriction with BD AM 133 
restriction with parallel input processing 60 
restriction with RPS feature 96 
restriction with variable-length records 24 
trailer label, user 42-45 
TRC (see table reference character) 
TRTCH 85 

TRUNC macro instruction 
description 83 

to terminate buff er processing 74 
truncated blocks, format-F records 23 
truncated format-U record 30 

TTR (see address, direct-access storage device, relative) 
TYPE=T operand 70-72 
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U-format records {see format-U records) 
UCS image 

relationship with SETPRT 88 
UHL (user header label) 42-45 
undefined length records {see format-U records) 
UNIT operand of the DD statement 37 
unlabeled magnetic tape 20-21 
UPDAT option 

{see also update mode) 

EODAD routine entered for BSAM 38 

for updating a sequential data set 94 

restriction with 

chained scheduling 92 
search direct operation 93 
SYSIN/SYSOUT data sets 69 

opening a data set 35 

updating a sequential data set 94 

with spanned records 26 
update mode 

{see also UPDAT option) 

with format-U records 30 

withPUTX 78 

with simple buffering 81 
user catalog 149,150 
user header label (UHL) 42-45 
user label exit routine 

description 42-45 

exit list entry 43 

restriction for data sets on volumes without standard 
labels 44 

restriction for SYSOUT data sets 44 

with read backward 44,45 
user totaling exit routine 

control totals 

description 45-46 

exit list entry 45 

how specified 

image area address 46 

relationship with end-of-volume exit 46,47 

restricted to BSAM, QSAM 45 

save area 45 

totaling area 45-46 

variable-length and spanned records 46 
user trailer label (UTL) 42-45 
utility programs, use of 

IBCDASDI 135 

IDCAMS 136 

IEBCOPY 107 

IEHATLAS 66 

IEHDASDR 135 

IEHLIST 117,140 

IEHMOVE 99,160 

IEHPROGM 140,153 

initializing direct-access volume 20, 1 3 5 
UTL (user trailer label) 42-45 



variable-length record (format- V) 24-27 

segments 24,25,26 

spanned 25-28 

restrictions with SYSIN and SYSOUT data sets 27 

special considerations, with user totaling 46 

with parallel input processing 60 
variable-length record (format-D) 28-29 
version increment of generation data group 151 
VIO (virtual I/O) 67 
virtual I/O (VIO) 67 
V-format records {see format-V records) 
volume 

control 149 

defined 19 

direct-access 20 

{see also direct-access volume) 

disposition {see DISP operand) 

identification operand of DD statement 37 

index {see index) 

initializing 20 

labels {see labels, direct access) 

magnetic-tape {see magnetic tape volumes) 

positioning 70-74 

serial number 37 

switching 59,72,74,147 

table of contents {see VTOC) 
VSAM catalog 

forVS2 149,150 

generation data group base created in 150 
VS2 systems 

abnormal termination during open, close, or EOV 
processing 68 

action of DISP option 73 

cataloging data sets 149-150 

generation data group base 150 

releasing data sets and volumes 86 

restriction with 2540 86 

use of VIO (virtual I/O) 67 
VTOC (volume table of contents 19,20 

DSCB 157 

for ISAM data set 108 

initializing 135 

pointer 158 

w 

WAIT macro instruction 
description 64-65 
example 124 

when sharing a data set 56 
with basic access technique 62,64 

BISAM 64,122 

BDAM 56,64,133 
with QSAM parallel input processing 60 
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WRITE macro instruction 

add form 129,133 

description 63,64 

for format-U records 30 

in EODAD routine 38 

in SYNAD routine 39,40 

programming consideration 91 

supplying record length 96 

update form 131 

updating a partitioned data set 1 05 , 1 06 

updating a sequential data set 94,95 

used with BDAM 128,129,130 

used with note list .100 

when sharing a data set 55,56 

with basic access technique 62 

with K (key) 122,124 

with KN (key, new) 111,113,123,124 

writing a short block 96 
write validity check option 34 

123 

1403 Printer 

SETPRT macro for 88 
1600 BPI 85 
2305 Fixed Head Storage 

capacity 137 

overhead formula 137 

programming considerations 133 
2314 Direct Access Storage Facility 

capacity 137 

overhead formula 137 
2319 Disk Storage 

capacity 137 

overhead formula 137 
2400 Magnetic Tape Units 

recording density 85 
2540 Card Read Punch 

chained scheduling restriction 93 

punch error correction 86 
f 3203 Printer SETPRT macro for 88 
3211 Printer 

SETPRT macro for 88 
3330 Disk Drive 

capacity 137 

overhead formula 137 
3333 Disk Storage 

capacity 137 

overhead formula 137 
3340 Disk Storage 

capacity 137 

overhead formula 137 
3350 Disk Storage 

capacity 137 

overhead formula 137 
3400 Magnetic Tape Units 

recording density 85 
3525 Card Punch 

chained scheduling ignored 92 

record format 84 
3800 Printer 

JFCBE exit for 47 

SETPRT macro for 88 

table reference character 22, 25, 31 
7-track tapes 85 
800 BPI 85 
9-track tapes 85 
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